Parent/Child Specification

This parent/child specification allows more flexible output support, e.g., per library documentation. See ocaml.org/packages.

Rules

The rules are;

• .mld files may or may not have a parent .mld.
• Compilation units must have a parent .mld.
• The parent .mld file must be compiled before any of its children, and the children must be specified at the parent's compilation time.
• The output paths of .mld files and compilation units are subdirectories of their parent's output directory.
• The output directory of a .mld file x.mld with children is <parent_output_directory>/x, and its file name is index.html. That is to say, <parent_output_directory>/x/index.html
• The output directory of a .mld file x.mld without children is <parent_output_directory> /x.html
• The output directory of a compilation unit X is <parent_output_directory>/X/index.html

Note: The --pkg <package> option is still supported for backward compatibility in odoc >= v2.0.0, although it's now equivalent to specifying a parent .mld file.

Example

For example, let's consider John whose is Doe and Mark's father. Doe has children, Max, and page foo, whereas Mark has no children. That is to say, john.mld, doe.mld, mark.mld, max.mld, foo.ml respectively. For instance;

john.mld

{0 About John}

I'm John the father to {{!page-doe}Doe} and {{!page-mark}Mark}.

doe.mld

{0 About Doe}

I'm Doe, the;
- son to {{!page-john}John}
- brother to {{!page-mark}Mark}
- father to {{!page-max}Max}

I also own page {{!page-foo}foo}

mark.mld

{0 About Mark}

I'm Mark {{!page-doe}Doe}'s brother and I have no children.

max.mld

{0 About Max}

I'm Max, the child to {{!page-doe}Doe}

foo.ml

(** I'm foo, a page child to Doe *)

Compilation

$ ocamlc -c -bin-annot foo.ml
  && odoc compile john.mld -c page-doe -c page-mark
  && odoc compile doe.mld -I . --parent page-john -c page-max -c foo
  && odoc compile max.mld -I . --parent page-doe
  && odoc compile foo.cmt -I . --parent page-doe
  && odoc compile mark.mld -I . --parent page-john

The output of the compilation phase will be .odoc files, where each will be linked by invoking the odoc link command on them.

Linking

odoc link -I . <file>.odoc

$ odoc link -I . page-john.odoc
  && odoc link -I . page-doe.odoc
  && odoc link -I . page-mark.odoc
  && odoc link -I . page-max.odoc
  && odoc link -I . foo.odoc

The output of the odoc link command is an .odocl file, by default, in the same path as the original .odoc file.

Generating HTML

$ odoc html-generate --indent -o html page-john.odocl
  && odoc html-generate --indent -o html page-doe.odocl
  && odoc html-generate --indent -o html page-mark.odocl
  && odoc html-generate --indent -o html page-max.odocl
  && odoc html-generate --indent -o html foo.odocl
  && odoc support-files -o html

Then we inspect the contents of the html directory using;

$ ls -R html
  highlight.pack.js
  john
  odoc.css

  html/john:
  doe
  index.html
  mark.html

  html/john/doe:
  Foo
  index.html
  max.html

  html/john/doe/Foo:
  index.

Note: We generated HTML files only for this example, but it's very possible to generate files in other formats (i.e, latex and man-pages) using:

• $ odoc latex-generate -o latex <file>.odocl
• $ odoc man-generate -o man <file>.odocl

Of course there are different commands that odoc uses for other purposes; e.g., for inspection:

• odoc <html/latex/man>-targets ... takes a glimpse of the expected targets
• odoc compile-deps ... lists units (with their digest) that need to be compiled in order to compile the current compilation unit. The unit itself and its digest is also reported in the output.

For example, inspecting the dependencies required to compile foo.cmt, we run

odoc compile-deps foo.cmt

and we shall get

Stdlib aea3513d44d604b62eaff79ad12007b3
Foo 5ab79b5411a3c3476029260eda0b4a26
CamlinternalFormatBasics f562e7b79dbe1bb1591060d6b4e854cf

For more about odoc commands, simply invoke odoc --help in your shell.

Convention for installed packages

Locally, the build system can make arbitrary complex documentation page hierarchies. However, the generated HTML documentation is generally not installed as part of a package. Instead the documentation source code made of .mld pages is installed and might be used by a different driver.

Convention

In order for drivers to build consistent documentation for a package, the following convention should be followed.

• .mld pages are installed in a package's share directory, under the odoc-pages sub-directory.
• A page is the parent of every installed pages. The driver can freely name this page, for example it can be named after the package. In what follows, we refer to this page as the pkg page.
• If there is an installed index.mld file, the driver has to use it as content for the pkg page.
• If there is no installed index.mld page, the driver has to generate some content for the pkg page.

This convention is followed by the driver for ocaml.org, by the driver Odig and by the build system Dune.