forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
New post
+82
site/blog/2026/04/parseff.png
site/blog/2026/04/parseff.png
This is a binary file and will not be displayed.
+82
site/blog/2026/04/weeknotes-2026-15.mld
+82
site/blog/2026/04/weeknotes-2026-15.mld
···
1
+
{0 Weeknotes 2026 week 15}
2
+
3
+
Once again, the docs CI went down. This time, something had scribbled over the docker
4
+
partition and so we needed to do a full build from scratch. Fortunately the docs
5
+
themselves were not in a docker volume and so we didn't have to rebuild everything
6
+
to get the HTTP server up and running for ocaml.org. However, we did have to set a
7
+
full build going so that we can build docs for new packages.
8
+
9
+
This keeps happening, and is very annoying! So, that brings me onto the next topic:
10
+
day11.
11
+
12
+
{1 Day11}
13
+
14
+
I've posted multiple times about {{:https://tunbury.org/}Mark Elvers'} {{:https://github.com/mtelvers/day10}day10}
15
+
project. For me, it was an obvious extension of this to get it to build docs, and,
16
+
as with most of my work recently, I set Claude on the task. However, Claude failed
17
+
to integrate it nicely into the codebase. Taking a closer look at day10, it's a
18
+
specialised tool that does its thing really well, but isn't built in a way that
19
+
makes it easy to adapt in the ways that the docs needed. Clearly separating the AI
20
+
generated code from the hand-written code is very important, so rather than going
21
+
that route, I decided that I'd try to build a more general day10 with Claude - day11!
22
+
23
+
It's already at the point where it's been able to build the docs for all packages
24
+
in opam-repository relatively quickly. Running it on [dill], which is roughly
25
+
equivalent to [sage], where the docs are currently built, it takes about 6 hours or
26
+
so to build everything, where [sage] with ocaml-docs-ci takes several days.
27
+
28
+
Some intriguing directions we might take this in:
29
+
30
+
- It's a generic build plaform for opam packages, therefore could possibly be used
31
+
for easily executing binaries from opam packages.
32
+
- It can build _itself_ - including new/different dependencies. Interesting for
33
+
a self-modifying tool!
34
+
- It's easy to drop into a container with precisely the correct dependencies for
35
+
any package, so useful for debugging build failures. This is partially implemented
36
+
already.
37
+
- We can already provide overlay opam-repositories for testing of new/altered
38
+
packages
39
+
40
+
One really nice test of whether the organisation of the libraries in day11 is correct
41
+
is whether we can plumb it into the docs-ci ocurrent pipeline easily, and have the
42
+
CLI tools for it coexist nicely.
43
+
44
+
{1 Odoc performance}
45
+
46
+
Running odoc on with some of the oxcaml libraries exposes some critical weaknesses
47
+
of the current code - in particular {{!/site/blog/2026/03/page-"weeknotes-2026-13".section-"oxmono-docs-build"}performance problems} with particular styles of
48
+
code. We can't build the docs for Anil's {{:https://github.com/avsm/oxmono}oxmono}
49
+
repo with GHA as it simply runs out of memory. I've therefore been investigating
50
+
some of the more egregious memory problems. I've got quite a few patches already
51
+
with some good results, but nothing yet that's going to make it into upstream
52
+
odoc without some more testing.
53
+
54
+
{1 Other bits and bobs}
55
+
I had fun hour or so putting together an odoc plugin to replicate the experience of
56
+
davesnx's {{:https://davesnx.github.io/parseff}parseff site}. The plugin
57
+
is {{:https://tangled.org/jon.recoil.org/odoc-parseff-shell/}here}, and
58
+
to use it, see my modified parseff repo:
59
+
60
+
{@shell[
61
+
git clone https://github.com/jonludlam/parseff.git#odoc-plugins
62
+
opam switch create . --with-doc
63
+
dune build @doc
64
+
]}
65
+
66
+
{%html:
67
+
<figure>
68
+
<a href="https://jon.ludl.am/experiments/parseff"><img src="parseff.png" alt="A screenshot of the parseff site"></a>
69
+
<figcaption><em>A screenshot of the parseff site produced by the plugin</em></figcaption>
70
+
</figure>
71
+
%}
72
+
73
+
There are a number of advantages and disadvantages to this. As @davesnx {{:https://sancho.dev/blog/ocaml-documentation-as-markdown}wrote},
74
+
his concern with the markdown output was to be able to integrate the odoc output seamlessly
75
+
with an existing site, and it does this very well. However, it's at a cost - we lose links
76
+
in the API docs, links to source, the source rendering itself, and so on. Whereas the plugin
77
+
I made keeps all of those nice features, but is still tricky to integrate with a larger site.
78
+
79
+
80
+
81
+
82
+