Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc: parent-child convention for installed packages #1011

Merged
merged 4 commits into from
Nov 29, 2023
Merged

Doc: parent-child convention for installed packages #1011

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
285e9c5
Doc: parent-child convention for installed packages
Julow Sep 28, 2023
132f52e
tentative convention for building installed package's doc
panglesd Oct 20, 2023
fdc1a75
Remove the "index" tentative fix
Julow Nov 10, 2023
5d0543c
convention: Remove paragraph on source rendering bug
Julow Nov 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions doc/parent_child_spec.mld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -19,6 +21,8 @@ The rules are;
{b 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.

{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;
Expand Down Expand Up @@ -157,3 +161,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.
- 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.

When the rendering of source code is enabled, the source tree will be named
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think any driver that follows this spec renders source today. If we're just documenting how things work right now we should omit this section.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

doc/driver.mld does that. This document doesn't describe what an existing driver does, rather what can be done by a driver today.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's better if we document what driver should do, so that there are no useless discrepancies between them.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this paragraph should be kept then.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

doc/driver.mld is a bad example for this - it follows literally none of the other conventions in the paragraph, as the intent back when it was first written was to show how odoc can be used more generally than just for making docs from installed opam packages.

We haven't quite figured out a convention for the sources, and it's not at all clear to me that the hierarchy will share the same namespace as the other package pages. As a concrete example, on ocaml.org cmdliner's pages currently appear under the hierarchy https://ocaml.org/p/cmdliner/latest/doc/ - e.g. tutorial.mld is https://ocaml.org/p/cmdliner/latest/doc/tutorial.html . I can easily imagine that there would be a desire for the source to appear under https://ocaml.org/p/cmdliner/latest/src/ in which case there's no namespace clash.

I'd quite like in this PR to just focus on what's actually implemented 'in the wild' and then we can have a separate discussion on these sorts of topics to bash out the wider question about what we should do to support the new features.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't agree that what exists in the wild is in the scope of this PR but I removed the paragraph to not interferes with the future changes.

[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}
and by the build system {{:https://github.com/ocaml/dune}Dune}.
Loading