To produce HTML documentation for your package pkg and its dependencies, first ensure that it is installed in your opam switch, then run:
odoc_driver <pkg>The output will appear in the directory `_html` by default.
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, 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.
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.
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:
$ 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
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 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.
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>}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 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.