From f4d12fa353f50b0c37000e9352d28f7617f9be7d Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Thu, 28 Sep 2023 11:36:33 +0200 Subject: [PATCH] Doc: parent-child convention for installed packages 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 --- doc/parent_child_spec.mld | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/doc/parent_child_spec.mld b/doc/parent_child_spec.mld index e775ce66d2..db3610b44a 100644 --- a/doc/parent_child_spec.mld +++ b/doc/parent_child_spec.mld @@ -157,3 +157,35 @@ 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}. +