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

Pretty cool! But I have found a typo.

I have a question! Do you like my new handle, "hexadecimo"?

Ouh yeah! 👏👏👏👏👏👏👏👏👏👏👏👏👏👏👏👏

Bravo! But what about category theory?

J'ai rien compris ! 🤣

Hello! You said your presentation was going to be 15 min. Hurry up for the other speakers! Your presentation is completely absurd! (ocaml-eglot is great!)

Look how cute he is!

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

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

Happy birthday Sabine!

Event reminder: Sabine's birthday (today)

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 this talk at Tarides, maybe you could use this opportunity to promote Outreachy? It was such a great internship!

Hello Paul-Elliot ! Would you mind speaking about Argos too? It is part of your "world after odoc 3"!

Hi Paul-Elliot! That reminds me: could you review my +1965456242,-4 lines PR from yesterday?

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