Generating Documentation

Prerequisites

Documentation in jbuilder is done courtesy of the odoc tool. Therefore, to generate documentation in jbuilder, you will need to install this tool. This should likely 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 the section Text formatting of the OCaml manual.

Additional documentation pages may by attached to a package can be attached using the Documentation Stanza.

Building Documentation

Building the documentation using the @doc alias. Hence, all that is required to generate documentation for your project is building this alias:

$ jbuilder 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:

$ jbuilder 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>.

Documentation Stanza

Documentation pages will be automatically generated for from .ml and .mli files that include ocamldoc fragments. Additional manual pages may be attached to packages using the documentation stanza. These .mld files must contain text in the same syntax as ocamldoc comments.

(documentation (<optional-fields>)))

Where <optional-fields> are:

  • (package <name>) the package this documentation should be attached to. If this absent, jbuilder will try to infer it based on the location of the stanza.
  • (mld_files <arg>) where <arg> field follows the Ordered set language. This is a set of extension-less, mld file base names that are attached to the package. Where :standard refers to all the .mld files in the stanza’s directory.

The index.mld file (specified as index in mld_files) is treated specially by jbulder. This will be the file used to generate the entry page for the package. This is the page that will be linked from the main package listing. If you omit writing an index.mld, jbuilder will generate one with the entry modules for your package. But this generated will not be installed.

All mld files attached to a package will be included in the generated .install file for that package, and hence will be installed by opam.

Examples

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))))