WIP INTERNAL TO ODOC TEAM - DO NOT SHARE

We are thrilled to announce the release of odoc 2.3.0! 🎉 This release is the result of almost a year of diligent work from the odoc team since the last major release of odoc 2.2.0, it comes packed with significant new features and improvements!

🗺️ Background & Roadmap

Before we delve into the feature highlights, some background on our roadmap and what comes next.

The lack of access to comprehensive documentation for OCaml libraries is one of the biggest pain points reported by the OCaml community, as highlighted in the 2022 OCaml survey (c.f. Q50).

This motivated the odoc and OCaml.org teams to jointly work on a centralised package documentation, that went live in April 2022, as part of the new version of OCaml.org.

With documentation for OCaml libraries readily available on OCaml.org, we now turn our focus on making sure that library authors have the tooling they need to create high-quality documentation.

Our roadmap highlights some features we believe will make the generated documentation significantly better for readers, and documentation-writing much more pleasant and rewarding.

This release is a significant milestone in implementing the features on our roadmap and is the precursor to a series of upcoming releases. Odoc 2.4.0 will follow shortly and will bring support for search. Stay tuned and follow our progress through the OCaml Platform newsletter!

🤝 Join Our Mission

While we are dedicated to developing the best tooling to generate and serve documentation on OCaml.org, creating a well-documented library ecosystem can only be a collective effort. Package authors: we're working hard to give you great tools, but we'll need all your help to create an ecosystem of well-documented libraries for OCaml!

If you find that writing documentation for your library isn't as straightforward as you would like, please do share your feedback with us.

🌟 Spotlight Features of Odoc 2.3.0

Here are a couple of the new features introduced in Odoc 2.3.0 that we'd like to highlight.

1. Table Support

   Table support is the last addition to the odoc language, after
   math expressions. Odoc supports two markup to include tables: a light one, and a
   heavy one. The light markup is similar to markdown's markup for table,
   producing tables that are readable in the source file as
   well.

   However, this markup has some limitation, since it only allows inline
   content in cells. It can also be difficult to read and mantain for big
   tables, without a proper editor support. For this reason, Odoc also
   provides a "heavy" markup, closer to the html one, with fewer limitations!

   Here is a table in heavy, light, and rendered form:

   ​​​​{t
   ​​​​Table | support
   ​​​​------|--------
   ​​​​is    | cool!
   ​​​​}
   

   ​​​​{table
   ​​​​{tr {th Table} {th support}}
   ​​​​{tr {td is} {td cool!}}
   ​​​​}
   

   Table	support
   is	cool!

2. Source Code Rendering

   Source code rendering is an extremely exciting new feature. Not only
   odoc is now able to generate a rendering of the source files (and
   source hierarchy) of a project, but it is also able to create direct
   links from the documentation to the implementation!

   This puts the documentation browsing to a new level, by helping to
   quickly answer any implementation-related question!

   The source code rendering is also tailored to OCaml, for instance with
   links from variables to their definition, something missing from
   traditional html-based source viewing such as github!