Hello Here is the latest OCaml Weekly News, for the week of January 19 to 26, 2021. Table of Contents ───────────────── How to get pleasant documentation for a library using Dune? Alt-Ergo 2.4.0 release First release of Art - Adaptive Radix Tree in OCaml perf demangling of OCaml symbols (and a short introduction to perf) Decimal 0.2.1 - arbitrary-precision decimal floating point Basic GitLab CI configuration OCaml Office Hours? json-data-encoding 0.9 VSCode OCaml Platform v1.6.0 release 0.3.0 of drom, the OCaml project creator Old CWN How to get pleasant documentation for a library using Dune? ═══════════════════════════════════════════════════════════ Archive: gasche announced ──────────────── 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. Problem description ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ For the sake of the example let's imagine that the library is called `Foo' and contains three modules `A', `B' and `C'. I'm using the standard dune approach of wrapped modules, so I get three compilation units `Foo.A', `Foo.B', `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 `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: 1. It should explain what the library is about. 2. It should briefly describe what each module does, so that users know which module they want to look at first. (Point 2 is especially important with "wrapped libraries", where it's not necessarily obvious which of the several modules is the main entry point with the important functions to look at first. In comparison, in a design where the "entry point" is in the `Foo' module, with `Foo.A' and `Foo.B' as more advanced submodules (or `Foo_A' and `Foo_B' in the old days) the user is guided to look at `Foo' first.) 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. [dune documentation on documentation] Rough ideas ╌╌╌╌╌╌╌╌╌╌╌ Roughly I see two ways to get what I want, that I have not tried yet: 1. I could write my own landing page for the library as a separate `doc.mld' file, use the `(documentation)' stanza to get it included in the built documentation, and use this as the entry point into my library. 2. In could write my own `foo.ml' module instead of using Dune's default wrapped-module scaffolding, inserting my own `module A = Foo__A' aliases, with documentation comments in the standard style. Then I suppose that `foo/Foo/index.html' would 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)? Thibaut Mattio replied ────────────────────── I think the documentation of [Streaming] is a great example of the option 1 you describe. The corresponding Dune setup can be found [here] That's also the approach we took for [Opium's documentation], although the index page is certainly not as impressive as Streaming's. [Streaming] [here] [Opium's documentation] gasche then said ──────────────── Thanks! It looks like these systems rely on an undocumented feature of the `(documentation)' stanza (or odoc), which is that a user-provided `index.mld' file will implicitly replace the automatically-generated `index.mld' file, giving a reasonably natural result. The opium documentation also [uses] the `{!modules: modulename ...}' markup directive, which is a way to include the module index within this manually-written landing page without having to duplicate the markup. Streaming¹ uses [inline html] instead to get a nicer-looking result, but it is too much effort. Maybe there is a better way, or the tools could be improved to make this easier. ¹: I'm ashamed to admit that I wasn't aware of this very nice library [Streaming], am I consuming the wrong sources of information on the OCaml ecosystem? Finally, the Opium documentation manifestly has a short synopsis for each module in its listing, which corresponds to my "It should briefly describe what each module does" requirement. I believe that this comes from the first line of the first documentation comment of the module. There are module-global documentation comments in the library I'm working on, but they do not include such first-line headers. Once I have the impression of understanding what is a good way to do this, I may try to contribute better documentation in `dune'. [uses] [inline html] [Streaming] Gabriel Radanne replied ─────────────────────── It looks like these systems rely on an undocumented feature of the `(documentation)' stanza (or odoc), which is that a user-provided `index.mld' file will implicitly replace the automatically-generated `index.mld' file, giving a reasonably natural result. I confirm this feature is here to stay, is the right one to customize your index page, and in the future will benefit from good support from odoc directly. The opium documentation also [uses] the `{!modules: modulename ...}' markup directive, which is a way to include the module index within this manually-written landing page without having to duplicate the markup. Streaming¹ uses [inline html] instead to get a nicer-looking result, but it is too much effort. Maybe there is a better way, or the tools could be improved to make this easier. I would strongly advise to use the `modules' markup directive, and to suggests output improvements on odoc's bug instead of hacking HTML together. We could absolutely add the synopsis of the module here, for instance. [uses] [inline html] Daniel Bünzli then said ─────────────────────── which is that a user-provided `index.mld' file will implicitly replace the automatically-generated `index.mld' file, giving a reasonably natural result. This is also the correct way to customize the landing page of your package for `odig' generated doc sets, see [here] for more information. I confirm this feature is here to stay, is the right one to customize your index page, and in the future will benefit from good support from odoc directly. There's an open issue about that [here]. [here] [here] Alt-Ergo 2.4.0 release ══════════════════════ Archive: OCamlPro announced ────────────────── We are pleased to announce a new release of Alt-Ergo! Alt-Ergo 2.4.0 is now available from [Alt-Ergo’s website]. An associated opam package will be published in the next few days. This release contains some major novelties: • Alt-Ergo supports incremental commands (push/pop) from the[ smt-lib] standard. • We switched command line parsing to use[ cmdliner]. You will need to use –