OCaml Changelog

RSS

Read the latest releases and updates from the OCaml compiler, OCaml infrastructure and the OCaml Platform Tools.

Odoc 3.1.0

We're excited to announce the release of odoc 3.1.0! This release brings several new features, important improvements, and bug fixes to OCaml's documentation generator.

What's New

OCaml 5.4.0 Compatibility

Full support for OCaml 5.4.0 has been added, ensuring odoc stays current with the latest OCaml releases.

New Output Formats and Options

  • Enhanced LaTeX Generator: New command-line arguments --shorten-beyond-depth and --remove-functor-arg-link provide more control over LaTeX output formatting

Key Improvements

Modernized Dependencies

The cmdliner compatibility layer has been removed as it's no longer needed, simplifying the codebase and reducing maintenance overhead.

Updated System Requirements

Support for OCaml versions prior to 4.08 has been dropped, allowing the project to leverage more modern language features and reduce compatibility complexity.

Better Configuration Management

Libraries from packages can now be referenced when added in odoc-config.sexp, improving flexibility in documentation project setup.

Improved LaTeX Output

  • Heading labels now use full paths to improve navigation and reference accuracy
  • Page and anchor separation in LaTeX labels prevents naming collisions

Bug Fixes

This release addresses several important issues:

  • Fixed META file parsing when dependencies are absent
  • Resolved rendering problems on medium screen sizes without global sidebar
  • Corrected occurrence generation for documentation CI systems
  • Ensured hidden pages never receive links, preventing broken references

Getting Started

To install odoc 3.1.0:

opam install odoc

For existing users, upgrade with:

opam upgrade odoc

Contributors

Special thanks to all contributors who made this release possible: @jonludlam, @Octachron, @davesnx, @dbuenzli, @panglesd, and @lukemaurer.

What's Next

We continue to work on expanding odoc's capabilities and improving documentation generation. The development team remains committed to making OCaml documentation more accessible and comprehensive.

Happy documenting!

See full changelog

### Added

Changed

Fixed

Odoc 3.0.0

We are delighted to announce the release of Odoc 3! This is a big release with loads of new features and bug fixes, and we encourage everyone to install it and try the new features!

This release has been cooking for a long time - it’s been more than a year since odoc 2.4 landed, and a huge amount of work has gone into this. Thanks to the many others who contributed, either by code or by comments: @juloo, @panglesd, @EmileTrotignon, @gpetiot, @trefis, @sabine, @dbuenzli, @yawaramin, and more.

Here is an overview of some major new features:

  • Search by type! Our detective sherlodoc will find your lost value given its type.
  • Odoc 3 features a global sidebar, allowing you to discover all documentation pages
  • The generated documentation include the source code. You can jump from any item in the documentation straight to its rendered source; no matter how much of OCaml’s complex module system you are using.
  • You can now add images to your documentation, as well as video and audio files Hierarchical documentation pages allow you to structure your documentation better
  • Reference items from other packages! With the ability to use cross-package links in your documentation, the generated documentation is now truly connected.
  • The build dependencies are friendlier with incremental build systems, allowing better shared build caches

With this release we’re including a driver that makes use of all the exciting new features of odoc. This driver has been used to create the docs site for the various odoc tools. However, Dune does not yet support odoc 3 since the Dune rules for running odoc via Dune need to be rewritten to reflect the odoc's new CLI and the new incremental build related capabilities odoc 3 brings.

Until Dune supports odoc 3, here is how to get started:

$ opam install odoc-driver # will install odoc 3
$ odoc_driver odoc odoc-parser odoc-driver odoc-md sherlodoc --remap

and point your browser at _html/index.html. This example shows odoc_driver creating the docs for exactly the 5 packages specified. While doing so, it will remap links to other packages to instead link to their documentation page hosted on ocaml.org (see "Remapping dependencies" in the odoc documentation).

If you try the above command, you'll note something interesting, and hopefully this will encourage you to run odoc_driver on your own packages before you release them, as then you'll be able to avoid slightly embarrassing post-release fixes like this one 😬

See full changelog

Added

  • Add png, pdf and jpeg image support to the latex backend by Octachron · Pull Request #1297 · ocaml/odoc · GitHub
  • Add header field to the json output by panglesd · Pull Request #1314 · ocaml/odoc · GitHub
  • Extract code blocks by name by panglesd · Pull Request #1326 · ocaml/odoc · GitHub

Changed

  • Fix suppress_warnings parameter by jonludlam · Pull Request #1304 · ocaml/odoc · GitHub
  • Fix suppress_warnings parameter by jonludlam · Pull Request #1304 · ocaml/odoc · GitHub
  • Disable warnings coming from linking implementations by jonludlam · Pull Request #1319 · ocaml/odoc · GitHub
  • Driver compile warnings by jonludlam · Pull Request #1323 · ocaml/odoc · GitHub
  • Fix "box model" for code blocks by panglesd · Pull Request #1317 · ocaml/odoc · GitHub
  • Store raw content of code blocks in parser's AST by panglesd · Pull Request #1325 · ocaml/odoc · GitHub

Fixed

  • Fix suppress_warnings parameter by jonludlam · Pull Request #1304 · ocaml/odoc · GitHub
  • Don't backtrace on invalid input in compile-deps by jonludlam · Pull Request #1313 · ocaml/odoc · GitHub
  • Fix indentation bug with verbatim in tags by jonludlam · Pull Request #1312 · ocaml/odoc · GitHub
  • Driver: Check for missing/unknown opam packages by jonludlam · Pull Request #1311 · ocaml/odoc · GitHub
  • Fix suppress_warnings parameter by jonludlam · Pull Request #1304 · ocaml/odoc · GitHub
  • Further fixes for virtual libraries by jonludlam · Pull Request #1309 · ocaml/odoc · GitHub
  • Fix issue #610 - odoc html-fragment not producing headings correctly by jonludlam · Pull Request #1306 · ocaml/odoc · GitHub
  • Fix classify when there are archives sharing modules by jonludlam · Pull Request #1310 · ocaml/odoc · GitHub

You can comment on this post on discuss.ocaml.org!

On behalf of the odoc team, I’m thrilled the announce the release of odoc 3.0.0 beta 1!

This release has been cooking for a long time - it’s been more than a year since odoc 2.4 landed, and a huge amount of work has gone into this. Thanks to the many others who contributed, either by code or by comments: @juloo, @panglesd, @EmileTrotignon, @gpetiot, @trefis, @sabine, @dbuenzli, @yawaramin, and more.

With this release we’re including a driver that knows how to use all of the exciting new features of odoc. This driver has been used to create the docs site for the various odoc tools.

Here are a selected set of features:

  • Rendered source! Jump from any item in the documentation straight to its rendered source; no matter how much of OCaml’s complex module system you are using.
  • Search by type! Our detective sherlodoc will find your lost value given its type.
  • Convenient warnings! Warnings are now clearly visible and useful, no longer buried among your dependencies’ warnings.
  • Self host your documentation, but link to ocaml.org for your dependencies.
  • More sidebars! Odoc 3 features a global sidebar, allowing you to discover the most hidden corner of underground documentation.
  • Image support! This cutting-edge feature now allows you to add images to your documentation. Video and audio come for free.
  • Fully cross-package links! The OCaml docs are now a true spider web. Prepare to catch bugs, and eat them.
  • Hierarchical documentation pages! We use a modular language. We don’t want a flat namespace for pages.
  • The build dependencies are friendlier with incremental build systems, allowing better shared build caches.
  • Quality of life improvements! Many improvements have been piling up since we started odoc 3. For instance: Add clock emoji before @since tag (@yawaramin, #1089)!

More explanation of these features is available at the odoc site, where we have documentation for authors, for users of odoc_driver, a cheatsheet, and differences from ocamldoc.

How can you help?

We need your feedback, both as authors and as users of documentation! Try things out using the new driver:

$ opam install odoc-driver    # don't forget to `opam update`
$ odoc_driver <package list>  # For instance: `$ odoc_driver brr odoc`
$ $YOUR_BROWSER _html/index.html

Many of those features’ implementations are not set in stone, but first versions. Please leave comments, either in this thread or as issues in the repository.

So, navigate already written documentation, and update your own docs to use the new features!

See full changelog

Highlight

  • Hierarchical documentation (@jonludlam, @panglesd, @Julow)
    Pages can now be organized in a directory tree structure.
    Relative and absolute references are added:
    {!./other_page.label}, {!//other_page}.

  • Improved sidebar and breadcrumbs navigation (@panglesd, @gpetiot)
    The documentation pages and the libraries of the entire package are shown on
    the left sidebar.

  • Added support for images, videos, audio and other assets
    The syntax is {image!/reference/to/asset} or {image:URL} for images.
    The syntax for {video...} and {audio...} is the same.
    (@panglesd, @EmileTrotignon, #1170, #1171, #1184, #1185)

  • Search using Sherlodoc (@panglesd, @EmileTrotignon, @Julow)
    A new search bar that supports full-text and type-based search.

Added

  • Experimental driver (@jonludlam, @panglesd)
    The driver builds the documentation for a collection of Opam packages using
    the newer Odoc features. It supports linking external packages to ocaml.org
    and markdown files.
    This is experimental and will break in the future.

  • Cross-package references (@panglesd, @Julow)
    Pages and modules from other packages can be referenced:
    {!/otherpackage/page}, {!/otherpackage/Module.t}.

  • Option to remap links to other packages to ocaml.org or other site.
    See the --remap option of the driver or the --remap-file option of odoc html-generate.
    (@jonludlam, #1189, #1248)

  • Option to compute occurrences of use of each identifiers
    The commands aggregate-occurrences and count-occurrences are added.
    (@panglesd, #976, #1076, #1206)

  • Added the odoc classify command (@jonludlam, #1121)
    Helps driver detecting which modules belong to which libraries.

  • Added --suppress-warnings to the CLI to remove warnings from a unit, even
    if they end up being raised in another unit through expansion
    (@jonludlam, #1260)

  • Add clock emoji before @since tag (@yawaramin, #1089)

  • Navigation for the search bar : use '/' to enter search, up and down arrows to
    select a result, and enter to follow the selected link. (@EmileTrotignon, #1088)

  • Fix a big gap between the preamble and the content of a page (@EmileTrotignon, #1147)

  • Add a marshalled search index consumable by sherlodoc (@EmileTrotignon, @panglesd, #1084)

  • Allow referencing of polymorphic constructors in polymorphic variant type
    aliases (@panglesd, #1115)

  • Added a home icon in the breacrumbs (@panglesd, #1251)
    It can be disabled with a CLI option.

  • Add a frontmatter syntax for mld pages (@panglesd, #1187, #1193, #1243, #1246, #1251)
    Allows to specify the title of a page, the order of sub-pages and other
    behaviors in the sidebar.

  • Added odoc-md to process standalone Markdown pages (@jonludlam, #1234)

Changed

  • The command line interface changed to support the new features.

    • Packages and libraries: odoc link must now be aware of packages and
      libraries with the -L libname:path and -P pkgname:path options. The
      module search path should still be passed with the -I option.
      The current package should be specified with --current-package=pkgname.
    • Hierarchy: odoc compile now outputs .odoc in the directory tree
      specified with --output-dir=DIR and the parent identifier must be
      specified with --parent-id=PARENT.
      The option --source-parent-file is removed.
    • Source code: Implementations are compiled with compile-impl instead of
      with compile. The options --cmt=.. and --source-name=.. are removed.
      Source code pages are generated with html-generate-source.
    • Assets: The commands compile-asset, html-generate-asset are added.
      The option html-generate --asset is removed.
    • Sidebar: The index is built using compile-index. The sidebar data is
      extracted from the index with sidebar-generate and passed to
      html-generate --sidebar=...
  • The syntax for @tag is now delimited (@panglesd, #1239)
    A @tag can now be followed by a paragraph or other elements.

  • Updated colors for code fragments (@EmileTrotignon, #1023)

  • Fixed complexity of looking up .odoc files (@panglesd, #1075)

  • Normalize whitespaces in codespans (@gpetiot, #1085)
    A newline followed by any whitespaces is normalized as one space character.

  • Reduce size of Odoc_html_frontend when compiled to javascript
    (@EmileTrotignon, #1072)

  • Overhaul of module-type-of expansions and shadowing code (@jonludlam, #1081)

  • Output file paths and labels in the man and latex backends changed to avoid
    name clashes (@Julow, #1191)

Fixed

  • Fix variant constructors being hidden if they contain hidden types
    (@jonludlam, #1105)
  • Fix rare assertion failure due to optional parameters
    (@jonludlam, #1272, issue #1001)
  • Fix resolution of module synopses in {!modules} lists that require --open
    (@jonludlam, #1104}
  • Fix top comment not being taken from includes often enough (@panglesd, #1117)
  • Fixed 404 links from search results (@panglesd, #1108)
  • Fixed title content not being picked up across pages when rendering references
    (#1116, @panglesd)
  • Fix wrong links to standalone comments in search results (#1118, @panglesd)
  • Remove duplicated or unwanted comments with inline includes (@Julow, #1133)
  • Fix bug where source rendering would cause odoc to fail completely if it
    encounters invalid syntax (@jonludlam #1208)
  • Add missing parentheses in 'val (let*) : ...' (@Julow, #1268)
  • Fix syntax highlighting not working for very large files
    (@jonludlam, @Julow, #1277)

Odoc 2.4.4

We're happy to announce the release of Odoc 2.4.4 which brings compatibility with OCaml 5.3!

See full changelog

Added

Odoc 2.4.3

We're happy to announce the release of Odoc 2.4.3!

This release includes three key fixes: we restored missing KaTeX headers for proper mathematical rendering, resolved an issue where ][ characters in code blocks were incorrectly interpreted as "code blocks with result" (now requiring explicit delimiters), and corrected the misprinting of type variables from ML files in OCaml 4.14 and later versions where multiple instances of the same type variable could be displayed with different names.

See full changelog

Fixed

  • Fix missing katex headers (@panglesd, #1096)
  • Allow ][ in code blocks, fixing issue #1137 (@Julow, #1149)
    This was interpreted as "code blocks with result", which now mandates a
    delimiter: {delim@lang[ code ]delim[ result ]}
  • Fix misprinting of type variables from ml files for OCaml 4.14 and later
    (multiple occurences of the same type variable could be named differently)
    (@Octachron, #1173)

Odoc 2.4.2

We've released odoc 2.4.2 with OCaml 5.2 compatibility and a few bug fixes.

See full changelog

Added

  • OCaml 5.2.0 compatibility (@Octachron, #1094, #1112)

Fixed

  • Fix issues #1066 and #1095 with extended opens (@jonludlam, #1082, #1100)

Odoc 2.4.1

The release of odoc 2.4.0 last month introduced a regression that caused Dune rules to fail in some cases. This release of odoc 2.4.1 fixes this issue.

See full changelog

Fixed

  • Revert to outputing a file (without content) when rendering a hidden compilation unit. This fixes cases where the dune rules would fail. (@panglesd, #1069)

Odoc 2.4.0

The odoc team is delighted to announce the release of odoc 2.4.0. It mainly contains support for search engines. There are of course bugfixes and smaller new features.

🌟 Spotlight Feature of Odoc 2.4.0 : Search

Odoc now support searching in the documentation ! The search is made to run in the browser, so that you do not need a server to enable search: you can have search on your documentation hosted on github pages or even locally on your machine.

No search engine is shipped with, you need to provide one, but all the facilities to make use of one are present. We adapted @art-w 's sherlodoc for seamless integration with odoc, alongside with new features. It is not yet released on opam, but we hope it will be soon.

You can already test sherlodoc and play with it on your own projects, there are instructions in its readme. Sherlodoc has fuzzy typed-based search like hoogle in the haskell world, and is made to work best for OCaml (unlike a general purpose search engine like elastic search).

Check the results on odoc's own online documentation : ocaml.github.io/odoc.

🤝 Join The 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.

See full changelog

Added

  • Add support for external search engines (@panglesd, @EmileTrotignon, #972) This includes the generation of an index and the display of the results in the UI (HTML only).
  • Display 'private' keyword for private type extensions (@gpetiot, #1019)
  • Allow to omit parent type in constructor reference (@panglesd, @EmileTrotignon, #933)

Fixed

  • Warn and exit when table(s) is not closed (@lubegasimon, #1050)
  • Hint when list(s) is not closed (@lubegasimon, #1050)
  • Fix crash on functors returning an alias (@Julow, #1046)
  • Fix rendering of polymorphic variants (@wikku, @panglesd, #971)
  • Add references to extension declarations (@gpetiot, @panglesd, #949)

Changed

  • Style: Adjusted line height in the TOC to improve readability (@sorawee, #1045)
  • Style: Remove font fallback to Helvetica, Arial (@Julow, #1028)
  • Style: Preformatted elements fallback to UA monospace (@toastal, #967)
  • Style: Sidebar is now stuck to the left of the content instead of the left of the viewport (@EmileTrotignon, #999)

Odoc 2.3.1

Following the release of odoc 2.3.0, we're releasing a patch release with odoc 2.3.1 that fixes support for OCaml 5.1.

See full changelog

Odoc 2.3.0

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!

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

Table Support

Table support is the last addition to the odoc language, and comes with two syntax flavours: 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!

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!

Using this features in odoc’s driver will require some work, but you can already have a preview of the feature by going to the odoc API website, which was built with the feature enabled. For instance, the Odoc_html 19 module is now populated with many Source links, jumping right into the implementation file 5! Directory pages to browser the implementation are also included 8 :smiley:

🗺️ Background & Roadmap

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.

See full changelog

Additions

  • Source code rendering (@Julow, @panglesd, @jonludlam #909, #996, #993, #982)
  • Handle tables markup (@panglesd, @gpetiot, #893)
  • Initial support for assets (@trefis, #975)
  • odoc-parser remerged (@jonludlam, #973) This includes table support (@gpetiot, @panglesd, ocaml-doc/odoc-parser#11 ocaml-doc/odoc-parser#14) and delimited code blocks with optional output (@jonludlam, ocaml-doc/odoc-parser#17)
  • Add a tooltip to references with text (@Julow, #945)
  • Add emoji to alerts in CSS (@yawaramin, #928)
  • Add common language in shipped highlightjs (@Julow, #953)

Bugfixes

  • Fix --hidden not always taken into account (@panglesd, #940)
  • Syntax highlight labels in function arguments (@panglesd, #990)
  • Ensure generated html ends with a newline (@3Rafal, #954)
  • Warn against tags in pages (@Julow, #948)
  • Remove unhelpful 'Unresolved_apply' errors (@gpetiot, #946)
  • Allow links and references in headings (@EmileTrotignon, @panglesd, #942)
  • Fix rendering of method types (@zoggy, #935)
  • Fix section labelling with submodules (@EmileTrotignon, @panglesd, #931)
  • LaTeX backend fixes (@Octachron, #921 #920)
  • html: Remove extra space in class declarations (@Julow, #936)
  • Fix rendering of unresolved references (@Julow, #957)

Odoc 2.2.1

As OCaml 5.1 is on the horizon, we're excited to announce the release of odoc 2.2.1. This latest version brings compatibility with the upcoming OCaml 5.1 release.

See full changelog

Additions

  • OCaml 5.1.0 compatibility (@Octachron, #956)

Odoc 2.2.0

See full changelog

Additions

  • New unstable option --as-json for the HTML renderer that emits HTML fragments (preamble, content) together with metadata (table of contents, breadcrumbs, whether katex is used) in JSON format. (@sabine, #908)
  • New maths support via {m ... } and {math ... } tags. (@giltho, @gpetiot, #886)
  • Various optimisations (@jonludlam, #870, #883)
  • Better handling of alerts and deprecation notices. (@panglesd, #828)
  • Handle language tags on code blocks (@julow, #848)

Bugfixes

  • Shadowing issues (@jonludlam, #853)
  • Layout fixes and improvements (@panglesd, #832, #839, #847)
  • Handle comments on class constraints and inherit (@julow, #844)
  • Disable the missing root warning (@jonludlam, #881)

Odoc 2.1.1

See full changelog

Additions

  • New subcommand to resolve references (@panglesd, @lubegasimon, #812)
  • Improved rendering of long signatures (@panglesd, #782)
  • Handle comments attached to open statement as floating comment, instead of dropping them (@panglesd, #797)
  • Empty includes (containing entirely shadowed entries) are now hidden (@panglesd, #798)

Bugs fixed

  • Fix a missing Result constructor during compile. This will cause some functor arguments to have different filenames (@jonludlam, #795)
  • Better memory/disk space usage when handling module alias chains (@jonludlam, #799)
  • Resolving class-type paths (ie., val x : #c) (@jonludlam, #809)
  • Skip top-level attributes while extracting the top comment. Fix top-comment extraction with PPX preprocessing (@jorisgio, #819)
  • Better handling of @canonical tags (@jonludlam, #820)
  • css: improved layout (@jonludlam, @Julow, #822)

Odoc 2.1.0

See full changelog

Additions

  • New subcommand to resolve references (@panglesd, @lubegasimon, #812)
  • Improved rendering of long signatures (@panglesd, #782)
  • Handle comments attached to open statement as floating comment, instead of dropping them (@panglesd, #797)
  • Empty includes (containing entirely shadowed entries) are now hidden (@panglesd, #798)

Bugs fixed

  • Fix a missing Result constructor during compile. This will cause some functor arguments to have different filenames (@jonludlam, #795)
  • Better memory/disk space usage when handling module alias chains (@jonludlam, #799)
  • Resolving class-type paths (ie., val x : #c) (@jonludlam, #809)
  • Skip top-level attributes while extracting the top comment. Fix top-comment extraction with PPX preprocessing (@jorisgio, #819)
  • Better handling of @canonical tags (@jonludlam, #820)
  • css: improved layout (@jonludlam, @Julow, #822)

Odoc 2.0.2

See full changelog

Additions

  • Compatibility with OCaml 4.14 (@patricoferris, @kit-ty-kate, #788)

Odoc 2.0.1

See full changelog

Bugs fixed

  • Man page renderer fails to output pages that have children (@jonludlam, @Julow, #766)
  • Fix resolution of unprefixed references to pages (@Julow, #755)
  • Fix reporting of ambiguous labels (@Julow, @jonludlam, #773, #781)
  • Allow referencing of labels in the top comment (@jonludlam, #771)

Additions

  • Strip unquoted spaces in identifiers for a more flexible reference syntax (@lubegasimon, @panglesd, #783)
  • Add context to messages raised in expansions of includes (@Julow, #780)

Odoc 2.0.0

Hot on the heels of the OCaml 4.13 announcement(s!), the odoc team is pleased to announce the release of odoc 2.0.0!

tl;dr: The new version produces much better output than the old version, it's the engine at the core of the package docs in v3.ocaml.org, and it also has a new website.

This release has been a long time coming -- years! -- and contains several notable improvements over the odoc 1.5 series: a new language model, a new rendering layer allowing output in several formats, and improved control over the output structure.

New Features

New Language Model

The internal library used by odoc that models the OCaml module system has been completely rewritten over a multi-year effort by @jonludlam and @Julow, according to a design by @lpw25. The rewrite gives odoc a much better understanding of the module system compared to the original implementation. This library is used for two main processes:

  1. To perform expansions, which is the process where odoc takes complex module type expressions like this one from tyxml:
module Make
    (Xml : Xml_sigs.T with type ('a, 'b) W.ft = 'a -> 'b)
    (Svg : Svg_sigs.T with module Xml := Xml)
  : Html_sigs.Make(Xml)(Svg).T
    with type +'a elt = Xml.elt
     and type +'a attrib = Xml.attrib

Then turns it into an output page containing the correct types, values, modules, includes, and documentation.

  1. To perform resolutions, which is where odoc handles complex paths found in OCaml source in order to calculate the correct definition link. For example, in the following snippet:
module type A = sig
  module M : sig module type S end
  module N : M.S
end

module B : sig module type S = sig type t end end

module C : A with module M = B with type N.t = int

type t = C.N.t

resolution is the process by which odoc determines which documentation page to take you when you click on C.N.t.

The new model has logic to handle many features of the OCaml language, as can be explored here.

A particularly important improvement is in handling canonical modules (explained in the link above). The upshot of this is that there should never be any more odd double underscores leaking into your docs!

For some more info on this, as well as the new output renderers, see our talk at the OCaml workshop last year

New Output Renderers

@Drup put a considerable amount of work into replacing the odoc 1.5 custom HTML generator with a new rendering layer. This features a new intermediate format allowing new output formats to be added far more easily than before.

Included in odoc 2.0 are renderers for HTML and man pages (both contributed by @Drup) and LaTeX (contributed by @Octachron). The LaTeX renderer has already been integrated into the OCaml build process to generate docs (see https://github.com/ocaml/ocaml/pull/9997 and related PRs). @jonludlam also made an alternative HTML renderer designed specifically for v3.ocaml.org. Finally, a new markdown renderer is being prepared by @lubegasimon and should land in the next release.

We look forward to many new renderers being created for the varied use cases present in the community!

Output Structure

odoc 2.0 introduces a new mechanism to specify the structure of the files produced. Although it's a relatively simple new feature, it nevertheless has enabled odoc to be used in new ways. In particular, it has allowed odoc to construct the package documentation for the new OCaml website, v3.ocaml.org. There is also an example driver, showing how odoc can be used to construct a stand-alone website for an OCaml package that contains fully-linked documentation for a package and all of its dependencies. This has been used to create odoc's new website.

New Drivers

Like the OCaml compiler itself, running odoc on your code requires careful sequencing of the invocations to produce the correct result. Fortunately both dune and odig understand how to do this, so most users don't need to know the details. If you want more than these tools provide though, we've written a simple reference driver, documenting exactly what's necessary to use odoc to produce rich documentation. A more complete (and more complex) example is the tool voodoo, which is being used to create the docs for v3.ocaml.org.

v3.ocaml.org

As previously posted, the new version of the OCaml website has been under development for some time now, and an important new feature is the integration of package listings, including documentation for every version of every package. More has been written about this elsewhere, but it's important to note that the new OCaml.org website required a preview version of odoc 2.0 to work. We've made a few bug fixes since then, so we will update the pipeline to use the released version very soon. For more info on the pipeline to build the docs, see our recent talk at this year's OCaml Workshop.

New Website

The website for odoc has been improved with guides for documentation authors, integrators, and contributors. This site is intended to grow over time with more content to help people write docs for their packages.

OCamldoc?

This release, particularly because of the new output renderers, puts odoc in a place where it supercedes OCamldoc in most respects. There are a few features we're missing (see the comparison in the docs), including most notably that we don't render the source (OCamldoc's --keep-code argument), and that there is no support for custom tags. If odoc is lacking features that you're currently relying on in OCamldoc, we'd love to hear from you!

More Docs!

Finally, I'd like to use this opportunity to launch an invitation. With v3.ocaml.org now showing all the package docs in their current state, I'd like to invite all our package authors, maintainers, contributors, and users to take a look over their favourite packages and see what the documentation looks like. Good documentation is one of the most important requests from the previous OCaml developer surveys, and with v3.ocaml.org as a new documentation hub, now is a great time to be making improvements where they're required. With this new release of odoc, previewing your docs should be as simple as dune build @doc.

Some packages already have great docs - a few examples are:

many others have more patchy docs. Let's fix that!

We're also looking for more contributors to odoc. It's much improved now, but there's still plenty more to do. Come and join the fun!

See full changelog

Breaking changes

  • Refactor the comment parser in preparation for it to be octavius 2 (@jonludlam, #621)
  • Remove odoc-parser into a separate repository (@jonludlam, #700)

Additions

  • New model for expanding and cross referencing (@jonludlam, @Julow, @lubegasimon)
  • New document output layer, supporting HTML, LaTeX and man page output (@Drup, @Octachron, @jonludlam, @Julow, @lubegasimon)
  • Experimental parent/child support for structured output (@jonludlam)
  • Add the ability to specifiy canonical paths for types and module types (@jonludlam, #596)
  • Several improvements to the HTML tree (@dbuenzli, #600, #605, #589, @Drup, #579)
  • Render module synopses in {!modules:...} (@Julow, #597)
  • Better HTML rendering (@dbuenzli, #607, #612, #615)
  • Better handling of signature comments (@Julow, #627, #629, #640, #643, #647, #654)
  • Centre, left and right alignment constructs now parse correctly (@lubegasimon, #624)
  • Allow reference to pages that contain hyphens and dots (@lubegasimon, #622)
  • Allow type definitions to be copied and pasted with correct syntax (@Drup, #626)
  • Install Ocamlary as a library for testing (@dbuenzli, #639)
  • Handle @canonical tags on compilation units (@Julow, #649)
  • Alias more when strengthening (@jonludlam, #653)
  • Light theme fixes (@xvw, #660)
  • Handle @canonical tags in the top-comment of modules (@Julow, #662)
  • Simplify paths referring to Stdlib (@jonludlam, #677)
  • New odoc command to report warnings encountered during compilation/linking (@Julow, #667)
  • Anchors on type extensions (@Julow, #684)
  • OCaml 4.13 support (@octachron, #687, #689)
  • Better errors/warnings (@Julow, #692, #717, #720, #732)
  • ModuleType 'Alias' support (@jonludlam, #703)
  • Improved test suite (@lubegasimon, #697)
  • Improved documentation (@lubegasimon, @jonludlam, #702, #733)
  • Strengthen module types (@jonludlam, #731)

Bugs fixed

  • Fix for resolving references in mld files (@jonludlam, #611)
  • Fix placement of documentation in module aliases (@Julow, #606)
  • Fix breakage involving includes and shadowing (@jonludlam, #603)
  • Don't link to hidden items (@lubegasimon, #583)
  • Don't remove docs of inlined includes (@Julow, #595)
  • Don't render shadowed values (@lubegasimon, #580)
  • Fix unresolved references in the first comment of a file (@Julow, #592)
  • LaTeX: Hardened description environments (@Octachron, #608)
  • Resolve references in module synopses (@Julow, #658)
  • Fix reference resolution in the presence of shadowing (@Julow, #682)
  • uwt now can be documented (@jonludlam, #708)
  • Fix resolution involving deeply nested substitutions (@jonludlam, #727)
  • Fix off-by-one error in error reporting (@asavahista, #736)

Odoc 1.5.3

See full changelog

Additions

  • Compatibility with OCaml 4.13 (ocaml/odoc#699, @Octachron)

Odoc 1.5.2

See full changelog

Additions

  • Compatibility with OCaml 4.12 (ocaml/odoc#531, @Octachron)

Odoc 1.5.1

See full changelog

Additions

  • Compatibility with OCaml 4.11 (#434, @kit-ty-kate)

Odoc 1.5.0

See full changelog

Additions

  • Add option to turn warnings into errors (#398, Jules Aguillon)

Bugs fixed

  • Emit quote before identifier in alias type expr (Fixes #391, Anton Bachin)
  • Handle generalized open statements introduced in 4.08 (#393, Jon Ludlam)
  • Refactor error reporting to avoid exiting the program in library code (#400, Jules Aguillon)
  • Build on OCaml 4.10 (#408, Jon Ludlam)

Odoc 1.4.2

See full changelog

Bugs fixed

  • Build on OCaml 4.09 (#383, Anil Madhavapeddy).
  • Handle OCaml 4.08 type and module substitutions (#381, Jon Ludlam).
  • Parser: better trimming of leading whitespace in code blocks (#370, Jules Aguillon).
  • Parser: allow references to operators containing : characters (#384, reported Sylvain Le Gall).
  • HTML: emit <meta generator> again (#378, Daniel Bünzli).
  • CLI: odoc html-targets was ignoring deeply nested modules (#379, Daniel Bünzli).
  • Fix bad internal usage of List.iter2 (#376, Yotam Barnoy).

Odoc 1.4.1

See full changelog

Bugs fixed

  • Messy formatting in large definitions due to lack of <span>s (#360, Thomas Refis).
  • Missing table of contents on .mld pages (#361, Rizo Isrof).
  • Missing space before polymorphic class names (#339, Kevin Ji).
  • Module type definitions printed with : instead of = (#344, Geoff Reedy).
  • Conjunctive types printed with * instead of & (#353, Florian Angeletti).
  • Type extensions (+=) printed without CSS classes found in other items (#348, reported Stéphane Lavergne).
  • High memory usage on large codebases (#361, Thomas Refis).
  • Build: double underscores in internal filenames (#357, Thomas Refis).
  • Development: test suite assumed that html5-tidy supports --mute (#345, Geoff Reedy).
  • Internal: refactored AST (#351, #364, Jules Aguillon).

Odoc 1.4.0

We are pleased to announce release 1.4.0 of odoc, the new, Dune-friendly documentation generator for OCaml and ReasonML.

odoc-output|690x444

You can install odoc and generate docs for your Dune project with:

opam update
opam install odoc
dune build @doc

Then, view the docs by opening _build/default/_doc/_html/index.html!

While release 1.4.0 has new features, it is mainly focused on stability and maintainability. See its full changelog here. The previous release, 1.3.0 last October, included a lot of new code. Because of concerns about its stability, we chose not to widely announce 1.3.0. So, this message serves as an announcement for both releases :) The full changelog for 1.3.0 can be found here.

In summary, compared with 1.2.0, odoc now has:

For now, we plan to continue improving the stability of odoc and the quality of its output. In the longer term, odoc has two significant goals:

  • To replace ocamldoc as OCaml's primary documentation generator. At the core of odoc is a powerful cross-referencer, capable of fully handling the complexity of OCaml's module system. Shortcomings in ocamldoc's ability to resolve cross-references in complex projects were one of the original motivations for starting odoc.

  • To create centrally-hosted, cross-referenced, searchable online documentation for all the published packages in opam, a “docs.ocaml.org.”

Thanks to the odoc users and contributors, and happy documenting!

See full changelog

Changes

  • All parsing errors are now recoverable warnings (#238).
  • Page titles are now level-0 headings ({0 ...}), and top-level sections within a page are level-1 headings ({1 ...}) (#217, Rizo Isrof).
  • Don't render definitions of externals (#275, Nik Graf).
  • Disable programming ligatures (#248).
  • Rename --root-uri option to --xref-base-uri (#223, Rizo Isrof).
  • Deprecate redundant reference kind annotations (#246).

Additions

  • Preliminary compatibility with the current 4.08 beta releases (#309, Jon Ludlam).
  • Paragraph headings ({4 ...}) and subparagraph headings ({5 ...}) (#217, Rizo Isrof).
  • odoc support-files-targets command (#232).
  • Recommend bsdoc for using odoc with BuckleScript (#269, Leandro Ostera).

Bugs fixed

  • Improve breadcrumbs on .mld pages (#293, Daniel Buenzli).
  • Display tables of contents in nested module and class pages (#261, Rizo Isrof).
  • Uncaught exception when parsing references to operators with - in them, such as @-> (#178).
  • Incorrect parsing of references to operators with . in them, such as *. (#237).
  • Assertion failure when processing optional arguments in an .ml file with a type annotation, when that type annotation uses an alias of 'a option (#101).
  • Assertion failure when two modules with the same name are found by odoc (#148, Jon Ludlam).
  • Verbatim blocks ({v ... v}) can now only be terminated if the v} is immediately preceded by whitespace (#71, reported Daniel Buenzli).
  • Wrong column numbers for errors reported in comments (#227, #253).
  • Restore parsing of ocamldoc-style reference kind annotations (#244).
  • Ordinary type keyword instead of and rendered in HTML for mutually-recursive types (#105, reported @Fourchaux).
  • nonrec keyword not rendered (#249).
  • and not rendered for mutually-recursive modules, classes, and class types (#251).
  • Outer comment attached to a module rendered when the module is included (#87, Jon Ludlam).
  • Polymorphic variant constructor documentation not rendered (#176, reported @steinuil).
  • Variant constructor and record field documentation styled differently (#260, Jon Ludlam).
  • Sloppy keyword markup in HTML output (#319).
  • Rendering of multiple constraint clauses (#321).
  • Incorrect order of functor arguments (#261, Rizo Isrof).
  • odoc html option -o now creates the output directory if it does not exist #171, #264 Rizo Isrof).
  • odoc html-targets output now includes path prefix given through -o option (#173, Rizo Isrof).
  • Allow -I and -o options to refer to non-existent directories (#32, #170, Daniel Buenzli).
  • Make odoc compile-targets match odoc compile (#273, Daniel Buenzli).
  • odoc compile-deps does not work on .cmt files (#162, Daniel Buenzli).
  • odoc html-deps now scans for .odoc files recursively (#307, Daniel Buenzli).
  • odoc html-targets ignores stop comments (#276, Daniel Buenzli).
  • odoc html-targets and odoc html-deps segfault on .mld pages (#277, #282, Daneil Buenzli).
  • --theme-uri option not propagated to some subpages (#318, Thomas Refis).
  • Binary files not opened in binary mode (#281, Ulrik Strid).

Build and development

  • Always print backtraces for unhandled exceptions (3d10feb).
  • CI on macOS (#216, Leandro Ostera).
  • Test runner improvements (#266, Rizo Isrof).
  • Fix esy builds in Travis (#301, Jon Ludlam).
  • Don't require make in the esy build (#308, Leandro Ostera).
  • Get rid of some large GADTs (#292, Jon Ludlam).
  • Remove dependency on bos (#305, Daniel Buenzli).
  • Remove dependency on rresult (#306, Daniel Buenzli).
  • Remove dependency on bisect_ppx, previously present in development checkouts (#316).

Odoc 1.3.0

See full changelog

Additions

  • Reason syntax output (#156, Patrick Stapfer).
  • BuckleScript support (#179, Leandro Ostera).
  • New CSS, appearance (#139, Rizo Isrof).
  • Table of contents for the sections in each page (fe26392).
  • Navigation breadcrumbs, and limit length of module paths in page titles (#150, Yotam Barnoy).
  • Syntax highlighting of code blocks (99f2be9).
  • Compiled odoc binary is now self-contained and requires no external files (bd3b53c).
  • --theme-uri option (#154, Rizo Isrof).
  • Option to convert .mld to HTML fragments rather than complete pages (#166, Rizo Isrof).

Bugs fixed

  • Use regular dashes in arrows to support ligature fonts (#180, Leandro Ostera).
  • Do not excessively indent code blocks (#133, Bobby Priambodo).
  • Always prepend page- to output file name when compiling .mld files (#183, Rizo Isrof).
  • Support floatarray type introduced in OCaml 4.06 (eb36158, Thomas Refis).
  • Support destructive type substitution (57cbb4e, Thomas Refis).
  • Render <i> tags in italics (#104, Thibault Suzanne).
  • Flush HTML output correctly (#167, Rizo Isrof).
  • Make HTML output more valid (#185, Leandro Ostera).
  • Various improvements to parsing, output, documentation, and the development workflow (Yotam Barnoy, Luke Czyszczonik, Mohamed Elsharnouby, Rudi Grinberg, Rizo Isrof, Leandro Ostera, Bobby Priambodo, Thomas Refis, Patrick Stapfer).

Build and development

  • odoc is now one repo.
  • Dropped several dependencies.
  • Considerable refactoring.
  • New commnt parser (78a6699).
  • Improved development workflow, including CONTRIBUTING.md, tests, coverage analysis, CI, and issue organization.
  • Initial NPM packaging (Leandro Ostera, #214).
  • Skeleton of odoc manual (Leandro Ostera, #203).

Odoc 1.2.0

See full changelog
  • Support for standalone documentation pages (.mld files) (#61).
  • Display [@@deprecated] attributes as the @deprecated tag (#57).
  • Allow each component of OCaml paths to be disambiguated using the kind-identifer syntax (part of #61).
  • Support OCaml 4.06.
  • Fix spurious leading blank lines in verbatim text (ocaml-doc/octavius#6).

Odoc 1.1.1

See full changelog
  • make odoc more noisy when generating html for hidden units
  • changed html-deps subcommand behavior: it now expects to be given a directory, not a single odoc file.
If you want to contribute to a new release announcement, check out the Contributing Guide on GitHub.