Great work on this site, and I love the domain name as well
As a bit of background on why documentation cross-linking has taken so long, there is a lonnnggg history intertwined with many people’s contributions to opam, build systems (ocamlbuild and dune), conventions (findlib and odig) and of course odoc itself. The major milestones along the way have been:
odoc 1.0, first began in 2014 as a quick project to pull together typing information from cmt[i] files, but which ran into the problem that it needs a consistent set of compiled cmt files to actually work, and so needs help from external tools to pull that set of compiled libraries together.
odig, which pulls together multiple opam packages (and a filesystem layout for metadata) and runs odoc on then. This allowed for the creation of https://docs.mirage.io a few years ago which cross-references a smaller number of packages
- opam-repo itself has had better and better bulk builds over the years to ensure that we can actually automatically compile all the artefacts needed for docs builds, thanks to efforts like health check and ocurrent.
- odoc 2.0, which featured a multi-year rewrite of the OCaml module resolver and introduced a new output IR. This forthcoming release was presented in this OCaml 2020 talk by @jonludlam.
And now with all these pieces in place, the OCaml documentation spring has arrived! The OCamlPro one posted here as the first of the “new batch” of mass documentation indexers, and I’m aware of concurrent efforts by the odoc/ocaml.org maintainer teams to push a central one out to ocaml.org, as well as by the MirageOS team who are refreshing docs.mirage.io with the latest and greatest. I’m sure when the dust has settled on all these indexers we can look for common pieces, but for now it’s lovely to see so much innovation happening at pace.
For the community: now is the time to fix your docstrings in your libraries, as there will many cool tools parsing and processing them, and rendering them into all kinds of output formats!
To the odoc contributors, thank you! The journey to get to this documentation site started here seven years ago:
Author: Leo White <firstname.lastname@example.org>
Date: Thu Oct 16 19:20:18 2014 +0100
@lefessan one thing I’m not sure about in your site is the “copyright library authors” claim. That’s murky legal ground – it’s worth establishing if the odoc HTML has gone through a compilation process and so is no longer copyright the authors (just as a binary output is not copyright the original source code). If the output is copyright the authors, then they have reasonable grounds to claim that you should also reproduce the copyright notice and other license restrictions. Personally, I prefer to claim that there is no copyright to the original authors in odoc output, and sidestep this issue.