Meet odoc, OCaml's Documentation Generator

Effective documentation is a cornerstone of software development. It helps developers understand how to use a language, its libraries, and its tooling, which leads to more robust and maintainable code. When it comes to OCaml, odoc is the wizard behind the scenes, ensuring developers not only understand OCaml's quirks but also become familiar with its libraries and tools. odoc powers the OCaml.org package documentation, so it's used widely by the entire OCaml community.

odoc is a documentation generator specifically designed for OCaml. It takes comments in the source code and generates documentation in HTML, man pages, and LaTex for PDF generation. Think of it like Sphinx or Javadoc specifically made for OCaml. In other words, what Sphinx is to Python, odoc is to OCaml. With odoc, you can automatically create documentation for your libraries.

See it in action! The odoc documentation pages, the Dream docs, and the online OCaml Packages docs (e.g., for cmdliner) were rendered using odoc.

History of odoc

OCamldoc, developed by Maxence Guesdon, was the earliest documentation generator for OCaml. It created docs in HTML by using comments in the source code tagged with (** and *). This allowed developers to produce documentation that closely followed the code and made it easy to keep the docs up to date. It provided a simple and efficient way to generate documentation for OCaml projects.

In recent years, there has been a transition to odoc, an open-source project that OCaml Labs and Tarides developed. This more modern and expandable documentation generator is built on the OCaml compiler's infrastructure. This makes odoc more tightly integrated with the language, so it supports all aspects of the OCaml language.

odoc offers several advantages over OCamldoc. It provides support for features like cross-referencing, modular documentation, and custom HTML theming, making it easier for developers to generate comprehensive and visually appealing documentation for their OCaml projects. Other recent features added to odoc include linking to source code and support for searching through the documentation.

The adoption of odoc marks a significant step forward to improve the quality and accessibility of OCaml documentation. It reflects the OCaml community's continuous effort to build an ecosystem of well-documented packages to improve OCaml developer experience and support the community's growth.

Generate Docs With odoc

odoc produces documentation by reading special comments embedded into the source code. odoc's rich markup language allows standard formatting elements such as bold, italic, lists, and code sections, as well as section headings or even tags (like @param) for adding custom data to specific aspects.

It's quite simple to use odoc because it reads the comments delineated with (** ... *). For example:

(** This is an OCaml docstring. It supports {b bold}, {e italic}, [code], and much more!
    Here is a list:
    - Item 1
    - Item 2
    And even a table:
    {t
    Table | support
    ------|--------
    is    | cool!
    } *)

Here is what it looks like after rendering:

odoc Features

Modules

In odoc, the basic unit of organisation is the module. The odoc tool generates one page for each module, module type, class, and class type for HTML, LaTex, or man pages output.

Extensivity

odoc will document all of the values, types, and classes, along with those specially-formatted comments, for each module.

Cross-Reference

odoc has an accurate cross-referencer that can calculate links between types, modules, module types, and more. A simple click will take you to the type's definition. So if you've ever been baffled by exactly what the t was in val f : t -> unit, odoc will link to it!

Expander

Figuring out a module's exact content from its signature is not always easy when using OCaml's expressive features such as include or module type of. odoc always expands such constructs to provide the reader the exact list of items available in the module!

Tarides and odoc

Tarides wants to improve the OCaml developer experience and remove the blockers for new developers to adopt OCaml. An ecosystem of well-documented packages is critical to language adoption and creating a great developer experience. We aim to provide package authors with excellent tooling, so they can write rich documentation. Tarides' commitment to improving odoc directly addresses these goals.

Tarides contributes significantly to the development of odoc. Tarides engineer Jon Ludlam has led the project and has been rewriting odoc's model for 2.0. We've added source code linking and support for search. Plus, we developed new odoc rules for Dune that can generate a link to the dependencies' documentation. We even created the odoc driver and CI pipeline that produce the package documentation for OCaml.org

Conclusion

Effective documentation guides developers through a language's intricacies, library functionalities, and tool utilisation. A documentation generator proves to be an indispensable conduit that translates complicated code into accessible, structured documentation. A dedicated documentation generator, like odoc, offers more than just documentation creation. It plays a crucial role in helping OCaml developers create well-documented libraries and applications, making it easier for programmers to work with the language and its rich ecosystem of libraries. It also encourages collaboration, accelerates learning curves, and crucially nurtures the growth of robust, well-documented, maintainable codebases. Tarides understands the huge benefit this gives developers, which is why we have a team dedicated to maintaining and improving odoc.

Join the odoc conversation on discuss.ocaml.org under the Ecosystem category by using the odoc tag. Also, please don't hesitate to open an issue on GitHub, as we're always striving to improve our products. Get started by installing odoc today!