Generating documentation of private libraries with dune

Ecosystem
1

I initialized my project using the recommended command

$ dune init proj project_name

from Quickstart — Dune documentation, and I want to generate its documentation. I used

$ dune build @doc @doc-private

as indicated in Generating Documentation — Dune documentation. It says that the generated documentation should be in _build/default/_doc/_html/<library> but it doesn’t say what <library> is. I would assume it is the library name from the dune file, but it is not: instead of the expected _build/default/_doc/_html/lib, my doc is in _build/default/_doc/_html/lib@5a6fo525np6/Lib (actually, it’s another seemingly random string of digits and lowercase letters).

As a consequence, some hyperlinks are broken in the generated html pages: they point to files which suppose a _html/Lib pattern instead of the _html/lib@5a6fo525np6/Lib one.

My dune files are

$ cat lib/dune
(library
 (name lib))
$ cat bin/dune
(executable
 (public_name project_name)
 (name main)
 (libraries lib))

Am I following the instructions wrong or is there a problem in the documentation or in the doc generation for private libraries?

Thanks.

Remark: in the above code “dune build @doc @doc-private”, both targets are actually needed, contrary to what Aliases — Dune documentation says.

2

Should I provide some more information? I gave the content of the files bin/dune and lib/dune in my initial post, and here is the structure of my project:

$ tree -L 2
.
├── bin
│   ├── dune
│   ├── main.ml
│   └── main.mli
├── _build
│   ├── default
│   ├── install
│   └── log
├── doc
│   ├── index.html
│   ├── lib@5c80a786e2f7
│   ├── odoc.support
│   └── project_name
├── dune-project
├── lib
│   ├── dune
│   ├── xxx.ml
│   └── xxx.mli
└── project_name.opam

and “zooming in”,

$ tree doc/ -L 2
doc/
├── index.html
├── lib@5c80a786e2f7
│   └── Lib
├── odoc.support
│   ├── fonts
│   ├── highlight.pack.js
│   ├── katex.min.css
│   ├── katex.min.js
│   └── odoc.css
└── project_name
    └── index.html

whereas I would expect

doc/
├── index.html
├── Lib
│   ├── index.html
│   └── Xxx
├── odoc.support
│   ├── fonts
│   ├── highlight.pack.js
│   ├── katex.min.css
│   ├── katex.min.js
│   └── odoc.css
└── project_name
    └── index.html

Actually, the generated doc/lib@5c80a786e2f7/Lib/index.html also expects something like the latter tree structure (but still with the name lib@5c80a786e2f7 instead of Lib). Indeed, the link for “Up – lib@5c80a786e2f7 » Lib” on that page points to doc/lib@5c80a786e2f7/index.html, which is a dead link (the page is at doc/lib@5c80a786e2f7/Lib/index.html).

3

You should probably report this issue on the GitHub repository of dune, as they could provide better guidance.

1 Like