A sandbox for proposing new features in odoc

For people interested in good documentation for their projects, but need a bit more from odoc.

I wanted to make a place where the broader OCaml community can experiment and propose odoc features: https://diskuv.github.io/odoc-sandbox/

I had two goals for the sandbox:

  • Let you visually see any proposals for new features to odoc. Hopefully this will make scoping the proposal easier.
  • No one should be blocked. Assuming the proposal is ok, it may take months (or even years) to implement. Any early adopter could use the custom Dune rules from the experiment to adopt in their own projects. Early adoption would be complex (custom Dune rules) but since the syntax shouldn’t change they won’t have to throw out their documentation.

I have one proposal in the sandbox and more will come later; there are also a few experiments using Sphinx and Markdown tools.

The first proposal would translate an odoc verbatim block:

{v
::code-block:: LANGUAGE

source code
v}

into syntax highlighted code. The visual results and the original .mli are available in experiment 400.

As I mentioned earlier, it has Dune rules which can be copied if you need it in your own projects. I don’t precisely know how it would be implemented for real in odoc (probably it would be a .mli transformer) but that is not the point. Instead if you have an implementation idea or simply love/hate the proposal, you can just go to GitHub and file an issue at https://github.com/diskuv/odoc-sandbox/issues.

4 Likes