ODoc: Easy Doc Generation for Reason
There are many reasons why odoc should be the default tool for generating API documentation for Reason. The most important one is that odoc is already an established tool for generating API documentation in the OCaml Platform and is therefore a first class citizen in the dune build system.
The build system plays an essential role in automatic documentation generation,
since odoc is not capable of understanding the structure of an OCaml / Reason
project on its own and needs to be fed with all the relevant information. As an
example, the build system tells odoc how to cross-reference dependent
modules with html
A few community members have been discussing options1 on how to make odoc more human-friendly on the commandline interface level, but in the end, this would require odoc to implement its own build system, which would be out of scope for this tool.
Another interesting issue is, that Reason uses its own build system for the frontend part, which is called BuckleScript. It is not only a fork of a lower versioned OCaml compiler (4.02.3, soon to be 4.06.0), but also has its own quirks on how modules are managed. An important part of our project is doing the research on how to efficiently drive odoc within the BuckleScript build process and find a streamlined way for easy adoption in the Reason community.
This project aims to integrate Reason into the existing odoc infrastructure, so here is a birds-eye view on what we want to achieve:
Introduce a cli option to make odoc output Reason formatted documentation (API interfaces)
Make sure that dune can pass a syntax option to odoc (via the odoc stanza)
Add UI elements in the generated documentation, which enables users to toggle between OCaml <--> Reason syntax while browsing through the docs
Add odoc support to BuckleScript and generate its API documentation in both syntax formats
Add instructions to the Reason and BuckleScript homepage and make it easy for Reason developers to migrate to automatic doc generation
Beside our main goals, we want to polish the output format and offer a different CSS file for more coherent Reason styling as well. In the end of this project, we will have a way better of browsing the offical Reason and BuckleScript API docs and want to encourage library maintainers to generate doc pages for their fellow Reason developers as well.
Reason Syntax Support
April 2019: We implemented a new odoc commandline flag2
--syntax to tell odoc to
yield Reason or OCaml flavored documentation, which was mostly done as a proof
of concept. We wanted to assess how hard it would be to reuse most of the odoc
rendering process and yield Reason syntax instead. Luckily it turned out to be
a quite straight-forward process (a few syntax fixes are still pending though6).
While we are able to output different syntax with our new cli flag, we were not
able to test our prototype with dune3. For the dune testing phase,
@rizo helped us out by integrating the syntax flag
via an environment variable4 called
ODOC_SYNTAX. This feature was
definitely a good idea, since we don't know yet if it's even necessary to
define a syntax flag by hand.
Now that we are capable of exporting different syntax outputs,
working5 on changes which makes odoc render both syntaxes by default and
allows the user to use an UI toggle in the generated docs (discontinued due
to other ideas on BuckleScript integration).
February 2020: With the rise of the new
reasonml.org documentation platform and our latest
efforts working on BuckleScript infrastructure, we finally got around drafting
out more concrete strategies on generating documentation from BuckleScript based
The outlines of these ideas are documented in a new project called
doc-tools7. The goal is to build a complementary toolchain which uses the
odoc model to expose JSON data, later on markdown to make it compatible with
reasonml.org API format.
Previous ideas of integrating Reason syntax into
odoc gave us a valuable
insights on what needs to be done for seamless integration. The biggest issue
we see with migration is that
odoc's html generation is not flexible enough
to extract and expose BuckleScript's APIs the way we need it, and we want to