Using odoc
This manual describes the features that are available and recommended for users to write great documentation using odoc.
- Cookbook
- Documenting your interfaces
- Writing documentation pages
- Examples of great
odoc usage
Cookbook
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 not be included in the generated table of contents and thus should be used to introduce examples, comments or other complementary notes.
Documenting your interfaces
...
Writing documentation pages
Files with the .mld extension are called 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.
Markup
Similarly to interface files, the familiar ocamldoc syntax can be used in pages. A documentation page can be seen as a single regular docstring in a separate file.
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.
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 Dune's configuration instructions for more details.
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.
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 Invoking odoc manually).
Examples of great odoc usage
...