ODoc: Easy Doc Generation for Reason

Last Update:
Apr 22, 2019
Tags:
OCaml
Author:
PS

Odoc is a tool for generating HTML documentation from OCaml / Reason modules. Back then in mid 2018, odoc was missing essential features which prevented us from using it in Reason related codebases. This project tackles some important tasks to make odoc easy to use in the Reason ecosystem.

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

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

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, we are working5 on changes which makes odoc render both syntaxes by default and allows the user to use an UI toggle in the generated docs. This will make it easier to cater to both communities and encourage them to build docs for both, OCaml and Reason.