From 285e9c59e61e3687370d5cc76c13277da0d67938 Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Thu, 28 Sep 2023 11:36:33 +0200 Subject: [PATCH 1/4] 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 | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/doc/parent_child_spec.mld b/doc/parent_child_spec.mld index e775ce66d2..5734279597 100644 --- a/doc/parent_child_spec.mld +++ b/doc/parent_child_spec.mld @@ -1,6 +1,8 @@ {0 Parent/Child Specification} This parent/child specification allows more flexible output support, e.g., per library documentation. See {{:https://ocaml.org/packages}ocaml.org/packages}. +{1 Rules} + The rules are; {ul @@ -19,6 +21,8 @@ The rules are; {b Note:} The [--pkg ] option is still supported for backward compatibility in [odoc >= v2.0.0], although it's now equivalent to specifying a parent [.mld] file. +{1 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; @@ -157,3 +161,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}. From 132f52ecf340b9f1a805a1c8bf8975fccfbc57f4 Mon Sep 17 00:00:00 2001 From: Paul-Elliot Date: Fri, 20 Oct 2023 16:06:26 +0200 Subject: [PATCH 2/4] tentative convention for building installed package's doc while still having reference to `page-index` work. Signed-off-by: Paul-Elliot --- doc/parent_child_spec.mld | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/doc/parent_child_spec.mld b/doc/parent_child_spec.mld index 5734279597..5658b5d3a4 100644 --- a/doc/parent_child_spec.mld +++ b/doc/parent_child_spec.mld @@ -177,18 +177,23 @@ 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. +- 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. + + The can decide to also include a [index] page as child of the [pkg] page. + - If it does not, then some references to the [index] page might be + unresolved. + - If it does, it will create a warning. +- If there is no installed [index.mld] page, the driver has to generate some + content for the [pkg] page. 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]. +[source] and will be a child of the [pkg] page. As a consequence, no installed +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} +This convention is followed by the +{{:https://github.com/ocaml-doc/voodoo}driver for ocaml.org}, +by the driver {{:https://erratique.ch/software/odig/doc/packaging.html}Odig} and by the build system {{:https://github.com/ocaml/dune}Dune}. From fdc1a75d467f9ae3e5c94f0673eb0ac83f1ba18b Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 10 Nov 2023 12:42:29 +0100 Subject: [PATCH 3/4] Remove the "index" tentative fix It's not possible to reference the package main page and this cannot be fixed now by tweaking the convention. --- doc/parent_child_spec.mld | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/doc/parent_child_spec.mld b/doc/parent_child_spec.mld index 5658b5d3a4..16b5b0e561 100644 --- a/doc/parent_child_spec.mld +++ b/doc/parent_child_spec.mld @@ -180,12 +180,8 @@ following convention should be followed. - 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. - + The can decide to also include a [index] page as child of the [pkg] page. - - If it does not, then some references to the [index] page might be - unresolved. - - If it does, it will create a warning. +- 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. From 5d0543c85feefd01893f3c02bcc61a35eb48775f Mon Sep 17 00:00:00 2001 From: Jules Aguillon Date: Fri, 24 Nov 2023 11:04:18 +0100 Subject: [PATCH 4/4] convention: Remove paragraph on source rendering bug --- doc/parent_child_spec.mld | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/parent_child_spec.mld b/doc/parent_child_spec.mld index 16b5b0e561..ec76c03400 100644 --- a/doc/parent_child_spec.mld +++ b/doc/parent_child_spec.mld @@ -185,10 +185,6 @@ following convention should be followed. - If there is no installed [index.mld] page, the driver has to generate some content for the [pkg] page. -When the rendering of source code is enabled, the source tree will be named -[source] and will be a child of the [pkg] page. As a consequence, no installed -page can be named [source.mld]. - This convention is followed by the {{:https://github.com/ocaml-doc/voodoo}driver for ocaml.org}, by the driver {{:https://erratique.ch/software/odig/doc/packaging.html}Odig}