[ANN] Release of odoc 2.4.0

Ecosystem
, ,
1

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.

:star2: 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.

:handshake: 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.

:gear: 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)
16 Likes
2

It would be nice to be able to use Vale together with odoc for language checking. It will make writing readable documentation much easier. It’s opensource tool and already supports multiple formats: Configuration - Vale

3

I am not sure they would accept a PR to add our syntax, or that we would want the maintain it. It also does not seem that they have a “plugin system” or a way to extend vale.
Maybe one day there will be support for markdown syntax in odoc, which would enable this tool (but only in .mld files which is not great).

4

They seem to have a plan for making format system extensible to make adding new formats easy: Make Vale's format support extensible · Issue #769 · errata-ai/vale · GitHub

1 Like
5

That would be nice !