ODoc: Easy Doc Generation for Reason

Introduction

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> tags.

A few community members have been discussing options¹ 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.

Goals

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 flag² --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 though⁶).

While we are able to output different syntax with our new cli flag, we were not able to test our prototype with dune³. For the dune testing phase, @rizo helped us out by integrating the syntax flag via an environment variable⁴ 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, we are working⁵ 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).

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 projects.

The outlines of these ideas are documented in a new project called doc-tools⁷. 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 the 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 try a more "JavaScripty" approach with more flexible tooling around the data model.