Weeknotes 2026 week 15

Once again, the docs CI went down. This time, something had scribbled over the docker partition and so we needed to do a full build from scratch. Fortunately the docs themselves were not in a docker volume and so we didn't have to rebuild everything to get the HTTP server up and running for ocaml.org. However, we did have to set a full build going so that we can build docs for new packages.

This keeps happening, and is very annoying! So, that brings me onto the next topic: day11.

Day11

I've posted multiple times about Mark Elvers' day10 project. For me, it was an obvious extension of this to get it to build docs, and, as with most of my work recently, I set Claude on the task. However, Claude failed to integrate it nicely into the codebase. Taking a closer look at day10, it's a specialised tool that does its thing really well, but isn't built in a way that makes it easy to adapt in the ways that the docs needed. Clearly separating the AI generated code from the hand-written code is very important, so rather than going that route, I decided that I'd try to build a more general day10 with Claude - day11!

It's already at the point where it's been able to build the docs for all packages in opam-repository relatively quickly. Running it on dill, which is roughly equivalent to sage, where the docs are currently built, it takes about 6 hours or so to build everything, where sage with ocaml-docs-ci takes several days.

Some intriguing directions we might take this in:

It's a generic build plaform for opam packages, therefore could possibly be used for easily executing binaries from opam packages.
It can build _itself_ - including new/different dependencies. Interesting for a self-modifying tool!
It's easy to drop into a container with precisely the correct dependencies for any package, so useful for debugging build failures. This is partially implemented already.
We can already provide overlay opam-repositories for testing of new/altered packages

One really nice test of whether the organisation of the libraries in day11 is correct is whether we can plumb it into the docs-ci ocurrent pipeline easily, and have the CLI tools for it coexist nicely.

Odoc performance

Running odoc on with some of the oxcaml libraries exposes some critical weaknesses of the current code - in particular performance problems with particular styles of code. We can't build the docs for Anil's oxmono repo with GHA as it simply runs out of memory. I've therefore been investigating some of the more egregious memory problems. I've got quite a few patches already with some good results, but nothing yet that's going to make it into upstream odoc without some more testing.

Other bits and bobs

I had fun hour or so putting together an odoc plugin to replicate the experience of davesnx's parseff site. The plugin is here, and to use it, see my modified parseff repo:

git clone https://github.com/jonludlam/parseff.git#odoc-plugins
opam switch create . --with-doc
dune build @doc

*A screenshot of the parseff site produced by the plugin*

There are a number of advantages and disadvantages to this. As davesnx wrote, his concern with the markdown output was to be able to integrate the odoc output seamlessly with an existing site, and it does this very well. However, it's at a cost - we lose links in the API docs, links to source, the source rendering itself, and so on. Whereas the plugin I made keeps all of those nice features, but is still tricky to integrate with a larger site.