118 lines
3.3 KiB
ReStructuredText
118 lines
3.3 KiB
ReStructuredText
.. _documentation:
|
|
|
|
************************
|
|
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 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 <http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html>`_.
|
|
|
|
Additional documentation pages may by attached to a package can be attached
|
|
using the :ref:`doc-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:
|
|
|
|
::
|
|
|
|
$ 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>``.
|
|
|
|
.. _doc-stanza:
|
|
|
|
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.
|
|
|
|
.. code-block:: lisp
|
|
|
|
(documentation (<optional-fields>)))
|
|
|
|
|
|
Where ``<optional-fields>`` are:
|
|
|
|
- ``(package <name>)`` the package this documentation should be attached to. If
|
|
this absent, dune will try to infer it based on the location of the
|
|
stanza.
|
|
|
|
- ``(mld_files <arg>)`` where ``<arg>`` field follows the
|
|
:ref:`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 dune. 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``, dune 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.
|
|
|
|
.. code-block:: lisp
|
|
|
|
(documentation ())
|
|
|
|
This stanza will attach three mld files to package foo. The ``mld`` files should
|
|
be named ``foo.mld``, ``bar.mld``, and ``baz.mld``
|
|
|
|
.. code-block:: lisp
|
|
|
|
(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:
|
|
|
|
.. code-block:: lisp
|
|
|
|
(documentation
|
|
((mld_files (:standard \ wip))))
|
|
|
|
.. _odoc: https://github.com/ocaml-doc/odoc
|