Odoc 3.0 planning

Hi everyone,

For many years we’ve had a team here at Tarides working away on Odoc, quietly adding new features, fixing bugs, speeding things up and generally enabling OCaml package mantainers to write good documentation. Up until recently, those improvements have mostly been incremental, but with the recent addition of some larger new features like search and source rendering we’ve found we need to think a bit more broadly and consider how these changes will fit into the larger ecosystem. We’re also thinking of how to extend the abilities of Odoc to handle more structure in the documentation, with better support for images, an improved sidebar, and a better ability to link to the docs of other packages.

We’ve therefore started the process that’s going to lead to Odoc 3.0, which will involve not only work on odoc itself, but also on ocaml.org, the documentation pipeline that produces the docs for ocaml.org, dune, and odig. It’s being done incrementally, so we’ve started with the core issues of how to structure your docs, how to do references both within the docs and across packages, what the output file structure will look like and how the breadcrumbs will reflect that. What we’ve posted so far is by no means the final version, and we’d love to get feedback on the suggestions we’ve got so far. Getting this right is surprisingly complicated, so the more people we have thinking about it, the better our chances of success!

So if you’re interested in writing or reading docs, I encourage you to head on over to the discussion we’ve just started on ocaml/odoc and join in the conversation!

16 Likes

Following the github discussion posted in this thread, we have published a new one that continues the previous one and focuses on assets and medias for Odoc 3.0.

Please tell us what you think!

1 Like