Document Tree model

Currently odoc has a notion of packages from which a module / page belong. This proposal extends that scheme to be more general, to allow for better handling of Libraries, and to allow for the sidebar to be more useful. We replace the 'package' notion with a general parent-child relationship as follows.

• Allow pages (mld files) and modules to have a parent/child relationship
• Pages can have page children too
• Only top-level modules need to have specified page parents
• Replace --package with appropriate use of --parent
• Pages refer to their children with a tag like {!child:page-Foo} or {!child:Module} - the latter will insert the text module Module : sig ... end with a link to the child. Note we already have {!modules:...} which we might use instead.
• Pages that don't explicitly refer to their children inline will get them appended to the bottom
• The side-bar on the page will be constructed from the
• support {!modulelist:Foo} and {!modulelist:page-Bar} to list the modules in Foo or the children in a page

This effectively adds support for libraries, both wrapped and unwrapped, by allowing modules to be parented under a library page, which is in turn parented under a package page. This is of course optional, and so wrapped libraries may be parented directly under a package page. Dune/Odig could create these files if they're not explicitly written.

The sidebar would be created by finding the top-most parent and creating a tree from there, using the headings in pages as the nodes of the tree. Rendering of the sidebar tree would render all headings in the current page as usual, but also the headings from sibling pages and ancestors.

Details

• Identifiers are modified such that the page type is extended:

type page = [ `Page of PageName.t | `SubPage of page * PageName.t ]

and the `Root constructor becomes

`Root of page * ModuleName.t

or maybe

`Root of page * Digest.t * ModuleName.t

• Non-hidden modules must be compiled with a parent page specified on the command line, for which an odoc file must exist (in order to determine its final output path)
• Pages may also be compiled with a parent page specified by the command line, for which an odoc file must exist.
• Pages should be compiled with children specified via the commandline (paths to odoc files), for which the files will not exist at point of compilation.
• Pages will output html files in the form <parent path>/<page name>.html
• Reference resolution scope (for 'roots') is done via filesystem include paths and is independent of the parent/child hierarchy.
• Reference resolution will allow pages to be parents, allowing authors to refer to them via {!page-parent.child} syntax.

odig compatibility

To create an odig style output, the following would be done:

• An index.html file is created with the alphabetical list of packages.
• A <package>.mld file is created and compiled first (e.g. alcotest.mld), specifying all non-hidden modules and any other mld files as children, with no parent itself.
• The exception is if an 'index.mld' file has been installed for the package (e.g. lwt), when this is used as the 'package' mld file. Children are specified as above.

Improved

• A 'packages.mld' file is created and compiled first, with the alphabetical list of packages.
• A 'package' mld file is created, specifying all non-hidden modules and any other mld files as children, with page-packages.odoc as parent
• The exception is if an 'index.mld' file is found this is used as the 'package' mld file. Children are specified as above.

sidebar

Sidebar is constructed at link time. The parent odoc file is loaded, and its parent and so on. These are scanned to find all the headings, up to the level of the header that includes us (or our ancestor), and these are assembled into the sidebar.

e.g.

packages.mld (no parent)

{1 Packages by name}

{2 A}
{{!child:alcotest}Alcotest}
{{!child:astring}Astring}

...
{{!child:async}Async}

{3 Not included in the sidebar...}

{2 B}
...

{1 Packages by Tag}

{!module:Astring}
...

astring.mld (page-packages.odoc is parent)

{1:package-astring Package astring}
Changes
{!child:Astring}

{2 Second level header}

{1 Included in sidebar}

Sidebar would be (note, all siblings show)

Package by name

A

Alcotest
Astring

 - Package astring
   - Second level header
 - Included in sidebar

Async

B

C

D

E

...

astring.cmti (page-astring.odoc is parent)

...

Sidebar would be: (note, no siblings at this level, parent only has one child)

Package by name

A

Package astring

    - String
    - Differences with the OCaml String module
    - Porting guide
      - Porting String.trim usages
    - Examples

Included in sidebar


...

docs.ocaml.org

packages/opampackage/version/Foo/index.html packages//opampackage/version/Foo/index.html

layout

• A 'packages.mld' file is created with the alphabetical list of packages.
• Many '.mld' files are created, with 'page-packages.odoc' as their parents
• A 'package' mld file is created and compiled, specifying all versions of the package as children
• A 'package' mld file is created for each package/version in each universe
• A 'version' mld file is created non-hidden modules and any other mld files as children, with page-packages.odoc as parent
• The exception is if an 'index.mld' file is found this is used as the 'package' mld file. Children are specified as above

universe hashes

for each version of each package:

calculate dependencies required to install it for the package, and each of its dependencies found, find the packages it depends upon and list them alphabetically using the versions in this universe as so:

astring,1.0.0 async,0.13.0 ... zarith,1.0.0

hash this, and record a map of universe hash to package name/version and text of this file

blessed universes

For each (package,version), we arbitrarily pick a particular universe as 'blessed'. If we are compiling the docs for this (package,version) in the blessed universe, its package.mld file will be parented directly under the main packages.mld file rather than under the universe-specific mld file.