jon.recoil.org
this repo has no description
1{0 JSON output}
2
3In order to embed the output of odoc within another website,
4the html generator for odoc has a mode where instead of producing HTML files, it will produce JSON files
5where the HTML files would have been. For example, if the HTML generator would have produced a file
6[/x/y/z/index.html], then when the [--as-json] flag is passed to [odoc html-generate], it will instead
7write the file [/x/y/z/index.html.json].
8
9In addition, there is a per-package 'global' sidebar json file.
10
11{1 Example page JSON}
12
13{@json[
14{
15 "header": "<h1>Module <code><span>Stdlib</span></code><a href=\"../../src/stdlib/stdlib.ml.html\" class=\"source_link\">Source</a></h1>",
16 "type": "documentation",
17 "uses_katex": false,
18 "breadcrumbs": [
19 {
20 "name": "Package index",
21 "href": "../../../index.html",
22 "kind": "leaf-page"
23 },
24 {
25 "name": "ocaml-base-compiler",
26 "href": "../../index.html",
27 "kind": "leaf-page"
28 },
29 {
30 "name": "stdlib",
31 "href": null,
32 "kind": "leaf-page"
33 },
34 {
35 "name": "Stdlib",
36 "href": "#",
37 "kind": "module"
38 }
39 ],
40 "toc": [
41 {
42 "title": "Exceptions",
43 "href": "#exceptions",
44 "children": []
45 },
46 {
47 "title": "Integer arithmetic",
48 "href": "#integer-arithmetic",
49 "children": [
50 {
51 "title": "Bitwise operations",
52 "href": "#bitwise-operations",
53 "children": []
54 }
55 ]
56 },
57 "source_anchor": "../../src/stdlib/stdlib.ml.html",
58 "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>.</
59p><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
60y modules</a>.</p>",
61 "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
62b/stdlib.ml.html#val-raise\" class=\"source_link\">Source</a><code><span><span class=\"keyword\">val</span> raise : <span>exn <span class=\"arrow\">-></span></span> <span class=\"type-var\">'a</span></span></code></div><div class=\"spec-doc\"><
63p>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
64ace\" ...."
65}
66]}
67
68The fields of the JSON are as follows:
69
70- [header] is a string containing HTML for the header of the page.
71- [type] field is either [documentation] or [source].
72- [uses_katex] is [true] if the page has math entries ([{m ...}] or [{math ...}]).
73- [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
74[page], [module], [leaf-page], [module-type], [argument-<number>], [class], [class-type], [file] or [source]
75- [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.
76- [source_anchor] is the URL of the corresponding source file, if it exists.
77- [preamble] is a string containing HTML for the preamble of the page.
78- [content] is a string containing HTML for the main content of the page.
79
80The data contained in these JSON files can be used to embed the HTML as rendered by odoc into a more complex site.
81The main requirement is that it is expected that an HTML page will exist at every location where a JSON file has been written.
82This is to ensure that relative links work.
83
84
85{1 Example sidebar json}
86
87{@json[
88[
89 {
90 "node": {
91 "url": "ocaml-base-compiler/index.html",
92 "kind": "leaf-page",
93 "content": "ocaml-base-compiler"
94 },
95 "children": [
96 {
97 "node": {
98 "url": null,
99 "kind": null,
100 "content": "compiler-libs.bytecomp"
101 },
102 "children": [
103 {
104 "node": {
105 "url": "ocaml-base-compiler/compiler-libs.bytecomp/Bytegen/index.html",
106 "kind": "module",
107 "content": "Bytegen"
108 },
109 "children": []
110 },
111 {
112 "node": {
113 "url": "ocaml-base-compiler/compiler-libs.bytecomp/Bytelibrarian/index.html",
114 "kind": "module",
115 "content": "Bytelibrarian"
116 },
117 "children": []
118 ...
119]}
120
121The 'global' sidebar JSON file consists of a list of objects, each containing a [node] field and a [children] field.
122The [node] field contains an object containing a [url], [kind] and [content]. The [kind] page is similar to that in the breadcrumbs above.
123The [content] field is an HTML string, and the [url] field is a string.