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 likely be done with opam:
$ opam install odoc
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 by attached to a package can be attached using the documentation-stanza
stanza.
Building the documentation using the @doc
alias. Hence, all that is required to generate documentation for your project is building 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:
$ dune build @doc-private
But this libraries will not be in the main html listing above, since they do not belong to any particular package. But the generated html will still be found in _build/default/_doc/_html/<library>
.
This stanza use 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 excluding wip.mld
in the current directory to the inferred package:
(documentation
(mld_files :standard \ wip))
(env
(<profile>
(odoc <optional-fields>)))
See dune-env
for more details on the (env ...)
stanza. <optional-fields>
are:
(warnings <mode>)
specifies how warnings should be handled.<mode>
can be:fatal
ornonfatal
. The default value isnonfatal
. This field is available since Dune 2.4.0 and requires Odoc 1.5.0.