Skip to content

Commit

Permalink
Doc: parent-child convention for installed packages
Browse files Browse the repository at this point in the history
This convention is already in use by Odig, Voodoo and Dune. It needs to
be specified as it needs to change in order to support assets and
complex hierarchies.

Co-authored-by: Paul-Elliot <[email protected]>
  • Loading branch information
Julow and panglesd committed Sep 28, 2023
1 parent b04251c commit 074810f
Showing 1 changed file with 31 additions and 0 deletions.
31 changes: 31 additions & 0 deletions doc/parent_child_spec.mld
Original file line number Diff line number Diff line change
Expand Up @@ -157,3 +157,34 @@ and we shall get
]}

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

{1 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.

{2 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.
- [index.mld] is the parent of every other pages. The driver can freely rename
this page, for example, it can be named after the package.
- Other pages are children of the [index.mld] page.

If no [index.mld] is installed, it's the driver's responsibility to generate
it.

When the rendering of source code is enabled, the source tree will be named
[source] and will be a child of [index.mld]. As a consequence, no page can be
named [source.mld].

This convention is followed by the drivers
{{:https://erratique.ch/software/odig/doc/packaging.html}Odig}
and {{:https://github.com/ocaml-doc/voodoo}ocaml.org}
and by the build system {{:https://github.com/ocaml/dune}Dune}.

0 comments on commit 074810f

Please sign in to comment.