Description
See ocaml/ocaml.org#1169 for the overall tracking issue.
status: incubate
This is an effort to bring a centralised documentation index to ocaml.org, using the new odoc tool. It requires building a large number of opam packages, gathering their build artefacts, and feeding them into a odoc driver such as odig, dune, or a forthcoming reference driver built into odoc itself (suitable for use from Makefiles or the OCaml compiler itself).
Thus far, there have been two separate builds of a larger OCaml package ecosystem:
- @dbuenzli with the b0 aggregate: https://b0-system.github.io/odig/[email protected]/
- @avsm with docs.mirage.io assembled from https://github.com/mirage/docs
The odoc developers have been steadily making progress on a large scale rewrite of odoc (see talk). This "model rewrite" eliminates from links in the generation of cross-references, and so makes it suitable for large scale deployment across the full set of opam packages. There has also been significant progress in adding support for more output formats, meaning that a central documentation service could move beyond just HTML output and perhaps offer search and direct editor query services.
At the moment, there are a few efforts that are complementary towards the deployment of this site:
- @jonludlam (the lead maintainer of odoc) is leading the release of the model rewrite and aiming for 100% coverage of the OCaml language.
- @thomasblanc and @AltGr are combining marracheck and the released odoc (without the model rewrite) into a unified site.
- @avsm is waiting to deploy the results to replace the rather creaky and manual https://docs.mirage.io build with something that can bulk build a selected set of packages.
Before we go into production with docs.ocaml.org, it would be good to have at least a couple of smaller community sites that demonstrate that they are maintainable. Once we're happy with the smaller scale deployments, we can begin regular bulk builds and deployments onto docs.ocaml.org.