unikernel/duniverse/dune_/doc/documentation.rst

@@ -0,0 +1,157 @@
+.. _documentation:
+
+************************
+Generating Documentation
+************************
+
+.. TODO(diataxis)
+
+   Split between:
+
+   - A "generating API documentation" how-to guide
+   - Some reference 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 <http://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html>`_.
+
+Additional documentation pages may be attached to a package using the
+:doc:`/reference/dune/documentation` stanza.
+
+Building Documentation
+======================
+
+To generate documentation using the :doc:`/reference/aliases/doc` alias, all
+that's required to is to build this alias:
+
+.. code:: console
+
+  $ dune build @doc
+
+An index page containing links to all the opam packages in your project can be
+found in:
+
+.. code:: console
+
+  $ open _build/default/_doc/_html/index.html
+
+Documentation for private libraries may also be built with
+:doc:`/reference/aliases/doc-private`:
+
+.. code:: console
+
+  $ 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 Stanza: Examples
+------------------------------
+
+The :doc:`/reference/dune/documentation` stanza will attach all the
+``.mld`` files in the current directory in a project with a single package.
+
+.. code-block:: dune
+
+   (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:: dune
+
+   (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:
+
+.. code-block:: dune
+
+   (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.
+
+.. code-block:: dune
+
+   (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.
+
+.. _odoc-options:
+
+Passing Options to ``odoc``
+===========================
+
+.. code-block:: dune
+
+    (env
+     (<profile>
+      (odoc <optional-fields>)))
+
+See :doc:`/reference/dune/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.
+
+.. _odoc: https://github.com/ocaml-doc/odoc
+
+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:
+
+.. code:: console
+
+  $ opam install sherlodoc