Generating Documentation¶

Prerequisites¶

Documentation in Dune is done courtesy of the odoc tool. Therefore, to generate documentation in Dune, you will need to install this tool. This should be done with opam:

$ opam install odoc

Writing Documentation¶

Documentation comments will be automatically extracted from your OCaml source files following the syntax described in the section Text formatting of the OCaml manual.

Additional documentation pages may be attached to a package using the documentation stanza. This stanza attaches .mld pages to packages rather than to executables.

Building Documentation¶

Dune’s generated documentation is package-oriented. The @doc alias builds HTML documentation for public libraries, that is, libraries with a (public_name ...), and for .mld pages attached to packages. Packages are declared with package stanzas or inferred from .opam files.

Executable stanzas are not documented as API pages by @doc. A project that contains only executables may therefore build @doc successfully without producing package API pages. To produce API documentation, put the documented code in a library with a (public_name ...) or attach .mld pages to a package.

To generate documentation using @doc, build this alias:

$ dune build @doc

An index page containing links to all the opam packages in your project can be found in:

$ open _build/default/_doc/_html/index.html

Documentation for private libraries may also be built with @doc-private:

$ dune build @doc-private

But these libraries will not be in the main HTML listing above, since they don’t belong to any particular package, but the generated HTML will still be found in _build/default/_doc/_html/<library>.

Documentation for public libraries can also be generated as JSON files with the @doc-json alias:

$ dune build @doc-json

These files are produced by odoc and can be used by external tools or custom documentation websites.

Documentation Stanza: Examples¶

The documentation stanza will attach all the .mld files in the current directory in a project with a single package.

(documentation)

This stanza will attach three .mld files to package foo. The .mld files should be named foo.mld, bar.mld, and baz.mld

(documentation
 (package foo)
  (mld_files foo bar baz))

This stanza will attach all .mld files to the inferred package, excluding wip.mld, in the current directory:

(documentation
 (mld_files :standard \ wip))

All .mld files attached to a package will be included in the generated .install file for that package. They’ll be installed by opam.

(documentation
 (files
  (glob_files_rec
   (doc/* with_prefix .))))

All files in the doc/ folder will be attached to the inferred package. The hierarchy between them will be preserved, relative to doc/ considered as the root.

Note

dune does not yet support building the documentation with a non-flat hierarchy, or with non-mld files. However, it supports installing those files following a convention, so that odoc_driver can build the docs with hierarchy and asset files.

Package Entry Page¶

The index.mld file (specified as index in mld_files) is treated specially by Dune. This will be the file used to generate the entry page for the package, linked from the main package listing.

To generate pleasant documentation, we recommend writing an index.mld file with at least short description of your package and possibly some examples.

If you do not write your own index.mld file, Dune will generate one with the entry modules for your package. But this generated file will not be installed.

Passing Options to `odoc`¶

(env
 (<profile>
  (odoc <optional-fields>)))

See env for more details on the (env ...) stanza. <optional-fields> are:

(warnings <mode>) specifies how warnings should be handled. <mode> can be: fatal or nonfatal. The default value is nonfatal. This field is available since Dune 2.4.0 and requires odoc 1.5.0.

Local Documentation Search Using Sherlodoc¶

If Sherlodoc is installed, generated HTML documentation will include a search bar. It supports search by name, documentation and fuzzy type search.

In can be installed with:

$ opam install sherlodoc