{0:top Using [odoc]}

This manual describes the features that are available and recommended for users
to write great documentation using [odoc].

+ {{:#cookbook} Cookbook}
+ {{:#interfaces} Documenting your interfaces}
+ {{:#doc-pages} Writing documentation pages}
+ {{:#examples} Examples of great [odoc] usage}

{1:cookbook Cookbook}

{2 Sections and headings}

Both API references and documentation pages can be split into sections that can
be introduced with level-1 headings. Each section can also have subsections
(level-2) and subsubsections (level-3).

Additionally paragraphs can be annotated with level-4 or level-5 headings.
Note that paragraph headings are {e not} be included in the generated table of
contents and thus should be used to introduce examples, comments or other
complementary notes.


{1:interfaces Documenting your interfaces}

...


{1:doc-pages Writing documentation pages}

Files with the [.mld] extension are called {e documentation pages} and should
be used to complement API references with tutorials or guides. They are
particularly suitable for OCaml and Reason because cross-references to
definitions, both in the current package and for external packages, are
supported.

{2 Markup}

Similarly to interface files, the familiar
{{:https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec351} ocamldoc}
syntax can be used in pages. A documentation page can be seen as a single
regular docstring in a separate file.

{2 Page title}

When defining a documentation page make sure to supply a page title as one is
not generated by default (unlike for API reference documents where the module
or module type name is used). The level-0 heading must be used for that
purpose. For example:

{[
{0 My page}
...
]}

Only one title is allowed per page, the following heading levels should be in
the range from 1 to 5 (inclusive). Don't worry, [odoc] will generate a warning
if you forget accidentally include multiple titles.

{2 Usage}

The recommended way to setup documentation pages for your project is by using
the Dune build system. It will automatically find and generate HTML for all
[mld] files in your project. See
{{:https://jbuilder.readthedocs.io/en/latest/documentation.html#documentation-stanza}
Dune's configuration instructions} for more details.

{2 Referencing pages}

Currently the generated HTML pages are not be automatically referenced in the
index page, you must manually add links to point to the pages in your document.

For example, if you have a page called [my_page.mld], you can create a
link to it with [{{!page-my_page}My page}] in your [index.mld] or
anywhere else in your documentation.

{2 Manual usage}

Generic [odoc] build instructions apply to documentation pages. You can compile
[mld] files manually with [odoc compile] (this is described in details in
{{:system-integrations.html#manual-usage} Invoking [odoc] manually}).


{1:examples Examples of great [odoc] usage}

...
