Odoc 3.0.0~beta1 • OCaml Changelog

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)