jon.recoil.org

Weeknotes 2026 week 24-25

I have now finally finished almost all of the end-of-term duties, incuding marking of 128 Foundations of Computer Science exam questions. Phew! It ended up being quite a week, with the unwelcome additional burden of having my car written off due to a minor prang.

The main things I've been working on have been finalising the new ocaml-docs-ci implementation, and working on a plan for "first class docs" in OCaml. The latter I've written up here. The former is currently running on a rebuilt https://dill.caelum.ci.dev, building docs for all versions of all packages.

First-class docs

I've written up a post on what 'First Class Docs' in OCaml might mean, and in parallel I've made a little tool to see how it feels. I've not put it on the main post, but I'll share a little video of it here:

It's a tiny tool that auto-builds docs for your switch, keeping them up to date automatically as packages are added and removed. It's got sherlodoc-based search, it can show docs in markdown in the terminal for any item in any package, completion of odoc-style references, and the completion is integrated with zsh so you can do `odd doc Odoc_<tab>` and it will show you sensible completions.

Next step is to create a skill for LLMs to use this tool. I'm pretty sure they'll find it very helpful!

Source is here: https://tangled.org/jon.recoil.org/odd

Docs CI

The work on docs-ci was not terribly exciting, but should be leading to a switch over in the next few weeks, once I'm happy that the service is more stable than the current one (which isn't a particularly high bar).

I've now left it running for a while just to see how it behaves. It's looking pretty good, though there were a few issues to iron out. The first was to do with epochs, which is a mechanism to allow deployment of new versions of odoc, sherlodoc, odoc_driver and so on whilst keeping the older version "live" until you want to switch over to the new version - the new epoch. The problem was that it was keying the epoch off the full solves of the tools rather than just the versions of the tools themselves. The consequence was far too rapid cycling of epochs, so I had to fix that. The second was that the switch to the new epoch did a synchronous GC of the older epochs, which led to a very long pause. Then the release of OCaml 5.5 turned out to be very useful, as while all the packages built as expected, none of the docs appeared. We have an override in the profile to be able to select the compiler version used to build odoc_driver and related tools, which was set to 'None' to mean 'latest version'. However, in this case, 'latest version' meant 'pin to the latest version of the compiler' as opposed to 'best version that has a solution'. This constraint, along with js_of_ocaml not yet working with OCaml 5.5, meant that there was no solution for the tools, hence no docs! The quick fix for this was to put a pin in place to OCaml 5.4.1 and the docs popped right out.

Some info: A full build took about 12 hours. This is on roughly the same hardware as the current docs ci, where it takes the best part of a week to do the same, so the day10/day11 architecture has made it much faster. Each snapshot builds about 17600 packages, in about 31,000 build layers, and 31,000 doc layers. The total space for one complete snapshot is on the order of 1.1Tb. The OCaml 5.5 release rebuilt most of the packages, so we're currenly up to about 2.3Tb of storage used.