1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
{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 here is highlighting an error in a reference in `odoc_parser.mli`.
{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].
|
