OCaml.org Now Uses odoc 3: What’s New?

The team behind the documentation tool odoc have been hard at work on the latest update. The recent release, odoc 3 (now 3.1!), brings new features that make navigating documentation easier and give authors more customisation options. Fortunately for users of OCaml.org, its package documentation pages now use odoc 3! This post will give you an overview of odoc, the new features, and how they improve the user experience on OCaml.org.

What is odoc?

Briefly, odoc is a documentation generator and rendering tool. It can read doc comments from source files and transform them into formats such as HTML, LaTeX, or manual (‘man’) pages (as of 3.1, odoc also supports an experimental markdown backend). It also enables cross-referencing, based on an extended version of ocamldoc markup, allowing you to create links for functions, types, modules, and documentation pages. Documentation generated by odoc can include links to the source code of functions, making navigating between the documentation and the code easier for the reader. The tool also automatically highlights syntax in code snippets to make documentation more legible.

You can learn more about odoc on its website and on its OCaml.org page.

What’s New With odoc 3?

3.0 was a big release, bringing multiple new features to the documentation generator. The main new features that came with the update are:

1. Search by type: Sherlodoc now lets users complete several specific searches in odoc documentation. These searches include searching by name, searching for constructors of a type, using _ to omit a subtype and search for consumers of a type, and several more specific search options. This makes it easier for users to find lost values and navigate the docs. Previously, Sherlodoc was a separate project, but now it is integrated into odoc’s code base.
2. Global sidebar: odoc can now generate global sidebars and breadcrumbs for pages. Previously, pages could ‘hack together’ their sidebars and breadcrumbs (this is what OCaml.org was doing), and now it can all be managed through one tool. The change offers greater choice for authors to organise and present documentation more clearly with minimal fuss.
3. Support for Manuals: odoc 3 comes with several features that help users create mld pages. These mld pages are written using odoc’s markup language. For example, the update gives users the ability to use hierarchical manuals and to link to the manual pages of other packages or API docs for libraries that aren’t in their direct dependencies.
4. odoc Driver: This driver helps users manage some of the more involved settings and features when running odoc. For example, rendering source code is now much easier than when the feature was first introduced in odoc 2, since odoc_driver now manages it for you.
5. Generated documentation and source code: You can now jump straight from items in docs to the source code using a ‘source link’, which navigates readers to a rendered version of the source code, without creating a custom driver.
6. Media: Images, videos, and audio files can now be added to documentation generated by odoc. This will make tutorials and documentation more intuitive and user-friendly, offering more ways to learn and share knowledge. Check out this OCaml.org tutorial to see images in odoc in action!
7. Cross-package links: Now, odoc lets you use cross-package links in documentation, meaning you can reference other package models and pages on a doc page. It allows users to generate interconnected pages of documentation to help readers navigate intuitively and smoothly.
8. Support for incremental build systems: The update makes managing build dependencies easier by supporting incremental build systems and allowing for better shared build caches. In the future, when odoc 3 rules have been implemented in [Dune], the integration with Dune’s cache will make this feature especially useful.

Tarides and odoc

Part of Tarides' mission is to encourage new users to adopt OCaml by making it easier to learn and use the language in their projects. Improving odoc was a quality-of-life upgrade for developers that made creating documentation easier. In turn, this benefits other users by hopefully encouraging more documentation to be generated.

In the same vein, we are also committed to maintaining and improving OCaml.org as a resource for the entire community. This includes upgrading it to use the latest versions of tools like odoc and testing and implementing new features.

OCaml is a language with many strengths, including its [secure-by-design features]. We want to give as many new people and organisations access to the right resources to make using OCaml easier. By making languages like OCaml mainstream, safer, and more efficient, code becomes more prevalent.

OCaml.org and odoc 3

Once odoc 3 had been released, the OCaml.org team started working on upgrading the package docs section of the site to use the new version. Since the tool underpins the entire documentation pipeline of the OCaml community, it was important to get buy-in from them and give them a chance to understand the proposed changes ahead of time.

So, the team shared updates on OCaml Discuss with links to the ‘staging’ version of OCaml.org, where users could explore changes ahead of time and share their feedback. It allowed them to help discover bugs and discuss how they felt about the implementation, which gave the maintainers crucial information to make the transition as smooth as possible. Previewing changes on the staging website also helped ensure the update did not break any existing features.

When the team were updating the docs pages, they needed to consider the significant changes to the CLI and new driver that odoc 3 had made, as well as the new feature of linking to other packages’ docs. They also adjusted the build and caching method employed by the documentation pipeline to improve support for incremental builds. With these background changes done, the website was ready for its makeover! You can check out PR #3124 to look at the patch.

Although updating OCaml.org to use odoc 3 is good for users, since they can take advantage of the new features, it’s also useful for authors who can explore the tooling before they use it themselves. For example, seeing how the global sidebar, breadcrumbs, and media are now implemented through odoc and supported on the website.

Try odoc 3 for Your Documentation!

You can try odoc 3 for yourself and experiment with the new features. The readme and installation instructions are on OCaml.org, which is an excellent place to get started. The maintainers of odoc welcome any feedback and input, either on Discuss or directly in the GitHub repo.

You can connect with us on Bluesky, Mastodon, Threads, and LinkedIn or sign up to our mailing list to stay updated on our latest projects. We look forward to hearing from you!