I’m working to publish a small library using Dune. The documentation automatically generated by
dune build @doc looks fairly unpleasant to me, as I don’t see an easy way to explain what the library is about. I’m creating this topic in case I am missing something simple, and to get other people to share their library-documentation practices or examples.
For the sake of the example let’s imagine that the library is called
Foo and contains three modules
C. I’m using the standard dune approach of wrapped modules, so I get three compilation units
Foo.C. Each module has a
.mli file with documentation comments.
When I run
dune build @doc, dune generates an
index.html file with basically no content, pointing to a
foo/index.html file with basically no content, pointing to a
foo/Foo/index.html looking like this:
Up – foo » Foo
module A : sig ... end
module B : sig ... end
module C : sig ... end
It’s easy to skip the first two pages, and use the third page as a landing page for the documentation of my library. However, this landing page is not very pleasant:
- It should explain what the library is about.
- It should briefly describe what each module does, so that users know which module they want to look at first. (Note: this one is in fact solved, see below.)
My problem is: what should I change in my Dune setup to be able to do this?
I have read the dune documentation on documentation, but I could not find an answer to this question.
Roughly I see two ways to get what I want, that I have not tried yet:
- I could write my own landing page for the library as a separate
doc.mldfile, use the
(documentation)stanza to get it included in the built documentation, and use this as the entry point into my library.
- In could write my own
foo.mlmodule instead of using Dune’s default wrapped-module scaffolding, inserting my own
module A = Foo__Aaliases, with documentation comments in the standard style. Then I suppose that
foo/Foo/index.htmlwould get this content in the way I expect.
They feel a bit complex to me, and (2) involves the tedious work of redoing the wrapping logic myself. I guess that (1) is not so bad, and I would be inclined to do this if it was documented somewhere as the recommended approach.
(Maybe there is some odoc option that would help solve this problem?)
Examples from other people?
Do you have a library built using dune with nice documentation? If so, can you show the documentation and the corresponding sources (in particular dune setup)?