JSON output

In order to embed the output of odoc within another website, the html generator for odoc has a mode where instead of producing HTML files, it will produce JSON files where the HTML files would have been. For example, if the HTML generator would have produced a file /x/y/z/index.html, then when the --as-json flag is passed to odoc html-generate, it will instead write the file /x/y/z/index.html.json.

In addition, there is a per-package 'global' sidebar json file.

Example page JSON

{
  "header": "<h1>Module <code><span>Stdlib</span></code><a href=\"../../src/stdlib/stdlib.ml.html\" class=\"source_link\">Source</a></h1>",
  "type": "documentation",
  "uses_katex": false,
  "breadcrumbs": [
    {
      "name": "Package index",
      "href": "../../../index.html",
      "kind": "leaf-page"
    },
    {
      "name": "ocaml-base-compiler",
      "href": "../../index.html",
      "kind": "leaf-page"
    },
    {
      "name": "stdlib",
      "href": null,
      "kind": "leaf-page"
    },
    {
      "name": "Stdlib",
      "href": "#",
      "kind": "module"
    }
  ],
 "toc": [
    {
      "title": "Exceptions",
      "href": "#exceptions",
      "children": []
    },
    {
      "title": "Integer arithmetic",
      "href": "#integer-arithmetic",
      "children": [
        {
          "title": "Bitwise operations",
          "href": "#bitwise-operations",
          "children": []
        }
      ]
    },
    "source_anchor": "../../src/stdlib/stdlib.ml.html",
    "preamble": "<p>The OCaml Standard library.</p><p>This module is automatically opened at the beginning of each compilation. All components of this module can therefore be referred by their short name, without prefixing them by <code>Stdlib</code>.</
p><p>In particular, it provides the basic operations over the built-in types (numbers, booleans, byte sequences, strings, exceptions, references, lists, arrays, input-output channels, ...) and the <a href=\"#modules\" title=\"modules\">standard librar
y modules</a>.</p>",
    "content": "<h2 id=\"exceptions\"><a href=\"#exceptions\" class=\"anchor\"></a>Exceptions</h2><div class=\"odoc-spec\"><div class=\"spec value external anchored\" id=\"val-raise\"><a href=\"#val-raise\" class=\"anchor\"></a><a href=\"../../src/stdli
b/stdlib.ml.html#val-raise\" class=\"source_link\">Source</a><code><span><span class=\"keyword\">val</span> raise : <span>exn <span class=\"arrow\">&#45;&gt;</span></span> <span class=\"type-var\">'a</span></span></code></div><div class=\"spec-doc\"><
p>Raise the given exception value</p></div></div><div class=\"odoc-spec\"><div class=\"spec value external anchored\" id=\"val-raise_notrace\"><a href=\"#val-raise_notrace\" class=\"anchor\"></a><a href=\"../../src/stdlib/stdlib.ml.html#val-raise_notr
ace\" ...."
}

The fields of the JSON are as follows:

• header is a string containing HTML for the header of the page.
• type field is either documentation or source.
• uses_katex is true if the page has math entries ({m ...} or {math ...}).
• breadcrumbs is a list of breadcrumb entries with members name, href and kind. If href is null then there is no index page at that location in the hierarchy. kind is one of page, module, leaf-page, module-type, argument-<number>, class, class-type, file or source
• toc contains the table-of-contents for the page. This consists of a list of objects containing fields title, href and children. title is a string containing HTML. href is the anchor in the page, and children is a list of more of these entries representing the sub-items in the table-of-contents.
• source_anchor is the URL of the corresponding source file, if it exists.
• preamble is a string containing HTML for the preamble of the page.
• content is a string containing HTML for the main content of the page.

The data contained in these JSON files can be used to embed the HTML as rendered by odoc into a more complex site. The main requirement is that it is expected that an HTML page will exist at every location where a JSON file has been written. This is to ensure that relative links work.

Example sidebar json

[
  {
    "node": {
      "url": "ocaml-base-compiler/index.html",
      "kind": "leaf-page",
      "content": "ocaml-base-compiler"
    },
    "children": [
      {
        "node": {
          "url": null,
          "kind": null,
          "content": "compiler-libs.bytecomp"
        },
        "children": [
          {
            "node": {
              "url": "ocaml-base-compiler/compiler-libs.bytecomp/Bytegen/index.html",
              "kind": "module",
              "content": "Bytegen"
            },
            "children": []
          },
          {
            "node": {
              "url": "ocaml-base-compiler/compiler-libs.bytecomp/Bytelibrarian/index.html",
              "kind": "module",
              "content": "Bytelibrarian"
            },
            "children": []
            ...

The 'global' sidebar JSON file consists of a list of objects, each containing a node field and a children field. The node field contains an object containing a url, kind and content. The kind page is similar to that in the breadcrumbs above. The content field is an HTML string, and the url field is a string.