View all changes

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