The world after Odoc 3

In March 2025, the face of the world changed: odoc.3.0.0 was released.

  • Added hierarchy to documentation, \(\leftarrow\) you need to specify your hierarchy

  • Added medias (images, audios, ...) and assets, \(\leftarrow\) you need to specify your media files

  • Added cross-package links \(\leftarrow\) you need to specify your dependencies

  • Added source rendering \(\leftarrow\) you need to update the build system

Actually not available: Locked behind tooling

  • dune build @doc did not enable the new features,

  • ocaml.org did not enable the new features.

The face of the world changed, but not much has changed for the average ocamleer.

So, what to do?

and odoc 3

1. Specify

Offer new stanza options for referencing other packages

(package
  (depends ...)
  (documentation
    (depends ...))

Offer new stanza options for assets and hierarchical documentation

(documentation
  (files <files and hierarchy target>))
           ; the stanza above includes assets / hierarchy

Examples

(documentation
 (files
  (glob_files *.mld)         ; Include mld files
  (glob_files *.png)))       ; and png images

(documentation
 (files
  (dune-project.mld as reference/dune-project.mld)))

(documentation
 (files
  (glob_files_rec            ; Include `doc/`, keep hierarchical
   (doc/* with_prefix .))))  ; structure for documentation

doc/index.mld            ->  <pkg doc root>/index.html
doc/tuto/index.mld       ->  <pkg doc root>/tuto/index.html
doc/tuto/tutorial1.mld   ->  <pkg doc root>/tuto/tutorial1.html

2. Respect the specification

There are two kind of "drivers" for odoc:

  • dune, bazel, ninja.

    • They build doc for a local project.

    • They rely on a their internal project knowledge.

  • odig, odoc_driver, voodoo.

    • They build doc for opam-installed packages.

    • They rely on a convention on installed files: eg pages are installed on <switch root>/doc/<pkg name>/odoc-pages/.

Install files for odig/ocaml.org's driver

Dune needs to respect the install convention given the user specification.

(documentation (files ...))
    ->  <switch>/doc/<pkg>/odoc-pages/index.mld
    ->  <switch>/doc/<pkg>/odoc-pages/logo.png
    ->  <switch>/doc/<pkg>/odoc-pages/reference/dune-project.mld

(package (documentation (depends ...)))
    ->  <switch>/doc/<pkg>/odoc-config.sexp

This enables the new features for odoc_driver.

Rewrite the "dune rules" to build documentation with the new CLI

$ odoc compile --parent-id <pkgname>/tuto/ tutorial1.mld

That looked a bit complicated \(\rightarrow\) Jon will take care of it.

.org and odoc 3

  • Write a new CI that uses odoc_driver to build the documentation

That looked a bit complicated \(\rightarrow\) Jon took care of it.

  • Use the output of the new CI in ocaml.org to get documentation
  • Handling redirection,
  • New CSS,
  • Replace Ocaml.org's sidebar and breadcrumbs,
  • ...

Converting to HTML is not as easy as it seems!

Argos

  • A tool to catch bitcoin's bad guys

  • Better than the concurrents!

Outreachy mentoring

  • Super nice experience

  • Sometimes very strong candidates

  • What you do is helpful

Thank you for your attention

Hello Paul-Elliot! Now that your presentation is finished, could you fill your 68765 missing weeklies?

Salut Chéri !
On se voit ce soir ? 💘❤️‍🔥

Hello Paul-Elliot! I'm sorry, I think speaking about Argos or outreachy will disturb the talk about odoc. Could you focus on odoc?

Hey, since you are giving a talk at Tarides, maybe you could use this opportunity to promote Outreachy? It was such a great internship!

Salut Paul-Elliot ! Comment vas-tu ? Dis, ça te dirait de parler d'Argos dans ta présentation ? Vu que t'as travaillé dessus...

Hi Paul-Elliot! That reminds me: could you review my +19242,-454 lines WIP commit?

Yo ! Ça te tente un coffee-chat ?

Hello Paul-Elliot! Sorry to interrupt your talk, but could you add metrics to measure the impact of your presentation? I'm available to help!

Hello Paul-Elliot ! I'm sorry to interrupt your talk but you should create proposals in order to do community work. Could you create a proposal for your talk?

←
⇱
→
0