forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
review
+81
+81
site/blog/2026/03/review.mld
+81
site/blog/2026/03/review.mld
···
1
+
{0 Review of the last few weeks}
2
+
3
+
It's time to take a step back and write a retrospective on the last few months of
4
+
vibecoding with Claude.
5
+
6
+
{1 What's been done}
7
+
8
+
Firstly let's see the various projects I've worked on and see what's been
9
+
accomplished.
10
+
11
+
{2 Dune}
12
+
13
+
Last year I wrote up my experiences writing the {{!//blog/2025/12/page-"claude-and-dune"}dune rules for odoc} with Claude.
14
+
The {{:https://github.com/ocaml/dune/pull/12995}pull request has been made}, representing a "feature complete" replacement for the current rules,
15
+
in that it can completely replace what's in dune now, but doesn't extend the rules for the new features of
16
+
odoc. Since then we've merged the first part of it -- though that's the bit that
17
+
wasn't written by Claude but by my colleague {{:https://choum.net/panglesd/}Paul-Elliot}. Fortunately after a brief
18
+
sabbatical working on {{:https://docs.slipshow.org/en/stable/}slipshow}, he's now back working with us and we'll be meeting soon to discuss the
19
+
next steps to get the rest of it merged.
20
+
21
+
In the mean time though, I've extended the rules by quite a lot. We've now got smarter rules that don't
22
+
pull in as many dependencies as the current PR, we've got support for assets, we've got support for source
23
+
rendering, there's markdown output and sherlodoc native support so you can run sherlodoc queries on the
24
+
command line. You can configure the prefix for your doc output, and pass arbitrary options to the
25
+
various invocations of odoc. All of this is being used as part of the process of generating this site,
26
+
but that's about all the testing its had. This will all have to be carefully reviewed then either
27
+
tacked onto the end of the current PR or we'll make new PRs for these. Very likely the latter, as the
28
+
current PR is hard enough to review as it is.
29
+
30
+
{2 Odoc}
31
+
32
+
Odoc itself hasn't had {i much} work done to it. What {i has} been done though is a new plugin system that
33
+
has been hugely enabling for building the new features below. I'm using dune's {{:https://dune.readthedocs.io/en/stable/sites.html#sites}site} feature for
34
+
the plugins, which really "just worked". It was very easy to add the feature and creating the plugins
35
+
has been equally easy. Building a whole variety of plugins has also been very useful in testing the
36
+
shape of the plugin API - I've made numerous changes to it as I've built various plugins and they expose
37
+
problems. I've also done a couple of more minor changes - one to allow 'custom tags', which the plugin
38
+
system uses heavily, and some improvements to the source rendering - there are many more links now
39
+
and we've got the ability to link to source from doc comments.
40
+
41
+
Let's take a brief look through the plugins I've made.
42
+
43
+
{3 Admonitions}
44
+
45
+
This is a feature we've wanted to add to odoc for a while - and we have a {{:https://hackmd.io/ETSOAmetTI-E3vrDk3Bfrw}design sketched out} for it.
46
+
47
+
@admonition.note This is a 'note' admonition.
48
+
49
+
This is more-or-less a throwaway plugin as we'll be doing this "properly" and won't need it. It made for
50
+
a nice first test though.
51
+
52
+
{3 Diagrams}
53
+
54
+
I've got 3 diagramming plugins - {{!/odoc-mermaid-extension/page-index}odoc-mermaid-extension}, {{!/odoc-msc-extension/page-index}odoc-msc-extension}
55
+
and {{!/odoc-dot-extension/page-index}odoc-dot-extension}.
56
+
57
+
{3 Interative pages (notebooks)}
58
+
59
+
The {{!/odoc-interactive-extension/page-index}odoc-interactive-extension} uses {{:https://github.com/art-w}art-w}'s {{:https://github.com/art-w/x-ocaml}x-ocaml} to add interactivity to the mld files.
60
+
Rather than using a fixed "execution engine" though, my fork is using {{:https://github.com/jonludlam/js_top_worker}js_top_worker} so we can
61
+
use different OCaml/OxCaml versions and load libraries as '#required'.
62
+
63
+
{3 Scrollycode}
64
+
65
+
The {{!/odoc-scrollycode-extension/page-index}odoc-scrollycode-extension} is based on {{:https://pomb.us}Rodrigo Pombo}'s work. You just add in
66
+
a few custom tags and some {{:https://tangled.org/jon.recoil.org/odoc-scrollycode-extension/blob/main/doc/notebook_testing.mld#L3}special markup}
67
+
in the source and you get lovely animated tutorials.
68
+
69
+
{3 HTML shells}
70
+
71
+
The "traditional" way that you embed odoc output into another webpage, like ocaml.org does, is to output
72
+
JSON. This is a bit annoying though, as it means once dune has finished, you need something else to come
73
+
in, pick up all the json files and write out your new site. The HTML shells extension is part of the
74
+
odoc plugin system, and allows you to swap out the HTML renderer for another one. I have two plugins
75
+
that use this system:
76
+
77
+
- {{!/odoc-docsite/page-index}odoc-docsite} which produces a more modern SPA-style site
78
+
- {{!/odoc-jons-plugins/page-index}jons-shell} which produces this website
79
+
80
+
81
+