Docs v3

doc/deprecated/dune

@@ -0,0 +1,6 @@
+(install
+ (section doc)
+ (files
+  (parent_child_spec.mld as odoc-pages/deprecated/parent_child_spec.mld)
+  (index.mld as odoc-pages/deprecated/index.mld))
+ (package odoc))

doc/deprecated/index.mld

@@ -0,0 +1,4 @@
+{0 Deprecated features}
+
+Odoc 2.x had a different way to specify the hierarchy of the output pages. This still works,
+though it is deprecated. Documentation for the feature may be found {{!page-parent_child_spec}here}.

doc/driver.mld

@@ -7,12 +7,12 @@ through several distinct phases until the HTML output is generated.
 For this reason, just like for building any multifiles OCaml project, [odoc]
 needs to be driven by a higher level tool. The driver will take care of calling
 the [odoc] command with the right arguments throughout the different
-phases. Several drivers for [odoc] exist, such as:
-{{:https://dune.readthedocs.io/en/stable/documentation.html}dune} and
-{{:https://erratique.ch/software/odig}odig}.
+phases. The {{!/odoc-driver/page-index}odoc-driver} package contains a "reference driver", that is kept up-to-date
+with the latest development of [odoc], 
 
-The [odoc] tool also contains a "reference driver", that is kept up-to-date
-with the latest development of [odoc].
+Several drivers for [odoc] exist, such as:
+{{:https://dune.readthedocs.io/en/stable/documentation.html}dune} and
+{{!/odig/page-index}odig}.
 
 This document explains how to drive [odoc], as of version 3. It is not needed to
 know any of this to {e use} [odoc], it is targeted at driver authors, tools that

doc/driver/dune

@@ -0,0 +1,7 @@
+(documentation
+ (package odoc-driver))
+
+(install
+ (section doc)
+ (files odoc-config.sexp)
+ (package odoc-driver))

doc/driver/index.mld

@@ -0,0 +1,99 @@
+{0 The odoc reference driver}
+
+{1 Quickstart}
+
+To produce HTML documentation for your package [pkg] and its dependencies, first ensure that it is installed in your
+opam switch, then run:
+
+{@sh[
+odoc_driver <pkg>
+]}
+
+The output will appear in the directory `_html` by default.
+
+{1 Introduction}
+
+[odoc_driver] is a tool that can be run to create and validate HTML documentation for OCaml packages.
+This includes the documentation comments in the interfaces and implementations of the modules, as well
+as [mld] files and their associated assets. In addition, the source code of the modules, if available,
+will be rendered with syntax highlighting and links. Also included is per-package search powered by
+{{!/sherlodoc/page-index}Sherlodoc}, and a global sidebar allowing easy navigation around the docs. It
+has a small number of options to allow for modification of the layout of what's produced. 
+
+{2 Drivers}
+
+[odoc_driver] is actually three drivers:
+
+- [odoc_driver] - The standard driver.
+- [odoc_driver_voodoo] - The driver adapted for producing the documentation used by ocaml.org.
+- [odoc_driver_monorepo] - An experimental driver for producing documentation of a dune-managed monorepo.
+
+What follows applies mostly to the first of these.
+
+{2 Documentation errors}
+
+[odoc_driver] will report errors that it discovers while generating documentation. In order that these
+errors can be fixed easily, it will ony report errors that are found within the packages that are selected
+on the command line, as opposed to those found in dependency packages. The errors will be reported on
+completion of the run. For example:
+
+{@sh[
+$ odoc_driver odoc-parser
+Deciding which packages to build...      
+Performing module-level dependency analysis...
+Starting the compilation process...
+Documentation generation complete. Results are in _html/
+Output from commands:
+/tmp/odoc-5f6831/odoc-parser/odoc-parser/odoc_parser.odoc
+---------------------------------------------------------
+File "src/parser/odoc_parser.mli", line 45, characters 30-45:
+Warning: Failed to resolve reference unresolvedroot(parse_coment) Couldn't find "parse_coment"
+]}
+
+which highlights 
+
+{2 Remapping dependencies}
+
+When producing documentation for OCaml projects, there are often links to types, modules, values and
+other items defined in other packages. In order that a complete set of documentation files is produced
+therefore, by default the documentation of the dependencies is produced. This may not always be
+desirable, so an option has been added to redirect links that would otherwise have gone to dependency
+documentation such that they instead link to the equivalent documentation page hosted on
+{{:ocaml.org}https://ocaml.org}. In order to enable this, pass the argument [--remap] to [odoc_driver].
+
+When run in this mode, the main index page will by default only list those packages whose documentation
+has been built.
+
+{2 Overriding the main index}
+
+The main index by default is a simple list of the packages that have been documented. This can be
+overridden by the `--index-mld` flag, which takes a path to an [mld] formatted file that will be used
+in place of the autogenerated one. All packages and all libraries are included in the scope of this
+page and therefore any built package can be linked to via the syntax
+
+{[
+{!/<package name>/page-index}
+]}
+
+and any library can be linked to via the syntax
+
+{[
+{!/<library name>/<Library Module>}
+]}
+
+{2 JSON output}
+
+When the option [--json-output] is passed to the driver, instead of producing HTML files it
+will instruct odoc to produce json output where the HTML would otherwise be. See the {{!/odoc/page-json}odoc documentation}
+for this feature.
+
+The per-page JSON output is written into the HTML output directory alongside where the HTML pages would ordinarily be,
+and the per-package sidebar is written to the package directory (ie, for package [odoc], with html output dir set to
+the default [_html], the sidebar JSON file is [_html/odoc/sidebar.json].
+
+
+
+
+
+
+

doc/driver/odoc-config.sexp

@@ -0,0 +1 @@
+(packages odoc sherlodoc)

doc/dune

@@ -9,7 +9,7 @@
   ocamldoc_differences
   odoc_for_authors
   cheatsheet
-  parent_child_spec))
+  json))
 
 ; Uncomment to run mdx on the documentation's code blocks.
 ; (mdx

doc/json.mld

@@ -0,0 +1,121 @@
+{0 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.
+
+{1 Example page JSON}
+
+{@json[
+{
+  "type": "documentation",
+  "uses_katex": false,
+  "breadcrumbs": [
+    {
+      "name": "🏠",
+      "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:
+
+- [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. 
+
+
+{1 Example sidebar json}
+
+{@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. 

doc/odoc-config.sexp

@@ -1,2 +1,2 @@
 (libraries fmt)
-(packages cmdliner)
+(packages odoc-driver cmdliner odig sherlodoc)

doc/odoc.mld

@@ -1,5 +1,5 @@
-@children_order dune odoc_for_authors cheatsheet features ocamldoc_differences interface parent_child_spec driver
-@short_title [odoc]
+@children_order odoc_for_authors cheatsheet dune features ocamldoc_differences interface driver json deprecated/
+@short_title The odoc documentation generator
 
 {0 The [odoc] documentation generator}
 
@@ -41,23 +41,11 @@ module types, and more. So if you've ever been baffled by exactly what the [t] w
 - an {e expander}, which can expand complex module-type expressions while preserving their structure, including comment, includes, and
 more. If you've ever wondered what values there are in your module [M : Base.Applicative.S with type t := u], [odoc] will show you!
 
-{1 For Library Authors}
+{1 For Authors}
 
-For guidance on how to document your OCaml project, see {{!page-odoc_for_authors}[odoc] for authors}.
+For guidance on how to document your OCaml project, see {!page-odoc_for_authors}.
 
 {1 For Integrators}
 
 To integrate [odoc] into your tool, webpage or any other
 setting, you'll need to understand {{!page-driver}how to drive [odoc]}.
-
-{1 Page Index}
-
-The main other pages of this site:
-- {!page-odoc_for_authors} gives information for [odoc] authors.
-- {!page-cheatsheet} provides a quick quide for [odoc] markdown.
-- {!page-features} explores [odoc]'s language features.
-- {!page-driver} describes how [odoc] produces documentation.
-- {!page-ocamldoc_differences} outlines differences from OCamldoc.
-- {!page-dune} shows how to create docs using Dune.
-- {!page-parent_child_spec} delineates parent/child specifications.
-- {!page-interface} describes [odoc]'s public-facing interface and their support guarantees.