Odoc: index for multiple packages, inter-package links, and local/global sidebar

Ecosystem
1

The odoc web page has some pretty neat features:

  • An informative welcome page “The odoc suite” for five constituent packages.
  • The links in the welcome page source (doc/main_index.mld) use the syntax {{!/doc/page-index}odoc}.
  • There are both “local” and “global” indexes in the left-side margin.

Are these currently added by manual tweaking or can they be accessed using dune/opam/odoc?

I tried to reproduce the original site as follows:

git clone git@github.com:ocaml/odoc.git
cd odoc
opam switch create . 5.1.0
dune build @doc

But the result is not the same: the file at _build/default/_doc/_html/index.html is just the default “multi-package” index, and there is just a single “contents” side menu.

Similarly, when I try to use these features for a much simpler project: ocaml-ortools (branch: odoc-mainpage), my inter-package links are not understood:

File "../../../../doc/main_index.mld", line 4, characters 2-49:
Warning: Failed to resolve reference /ortools_solvers/index Path '/ortools_solvers/index' not found
File "../../../../doc/main_index.mld", line 3, characters 2-33:
Warning: Failed to resolve reference /ortools/index Path '/ortools/index' not found

Am I doing anything wrong?

2

For non-obvious-reason you need to use dune build @doc-new :slight_smile: (and to enable Sherlodoc, searching by types, sherlodoc need to be installed in your switch).

3

Thanks @xvw for the suggestion. Unfortunately, however, it doesn’t seem to help with the welcome pages, the links, or the local and global indexes. For odoc, the only change I can see is that the main index is now a list of “local packages”, “switch installed packages”, and “private libraries”. This is even less useful for generating a web site for package docs!

4

Oh yes ! You are right ! I was able to deal with that using index.mld files and odoc_driver

5

Once this PR is finished and merged, dune will be able to build the same doc as odoc-driver.

(odoc-driver is used as part of the doc CI, so cross-package links/local and global sidebars are already available on the doc hosted on ocaml.org, see for instance odoc’s doc on ocaml.org.)

6

Perfect. I’ll try again when the PR is sorted out. Thanks to you both.