The OCaml Documentation Hub can be used to browse the sources and
the documentations of more than 2000 opam packages, following links
between them when useful. This is a work-in-progress, and we are
working on improving it with many more features, such as source
annotations with types, full-text and type-driven searches,
improvements in the general readability of documentation, etc.
The site is generated using an open-source tool called digodoc,
available on:
Digodoc is able to build a map of an opam switch, with links between
files, opam packages, ocaml libraries, meta packages and ocaml
modules. It is also able to generate documentation using odoc with
cross-indexes between all these kinds of packages.
At a first glance, this looks absolutely amazing, both in functionality and appearance. The cross linking between packages is fantastic. The view “package modules” is succinct and readable.
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:
commit ef91571cab31d9ece7af965ed52eaaff57a12efc
Author: Leo White <lpw25@cl.cam.ac.uk>
Date: Thu Oct 16 19:20:18 2014 +0100
Initial commit
@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.
My gratitude for the hard work everyone has done on this project is not adequately expressed by a cheap post on discuss.ocaml.org. This is a huge breakthrough, and our community is enriched immensely by this.
For authors who write a library with dune+opam, do you have any advice or starting point for checking that everything looks good before publishing a package on opam?
Congratulations, this is truly fantastic! This is honestly a best-of-breed implementation of any docs site I’ve seen. Beautiful, comprehensive, and fast!
I really struggled to find the source code of functions I use (esp when using libs that do module inclusion a lot, like Jane st libs). If it’s possible to link to source in github for a particular function, that would be amazing
rust and elm allow you to quickly switch between package versions, which I’ve found super useful
I’d just like to stress that odig documents OCaml package installs regardless of the package manager used as long the install structure follows these conventions (which are automatically followed by dune installs) .
Also for people using my packages, I’d just like to mention they may miss important documentation bits on https://docs.ocaml.pro until that issue is resolved.
Thanks @avsm , all these projects were indeed important milestones towards the creation of this site. However, I wouldn’t want this history perspective to give the wrong feeling that building this site
was easy, it is the result of a very good, long and hard work by the team at OCamlPro to make it work despite a road paved with many obstacles. It also benefited from OCamlPro’s long history of
innovative projects for the OCaml community, that lead for example in the past to Opam, Try-OCaml, Memprof/Memthol,Opam-builder, Learn-OCaml, the Typerex tools (ocp-indent, ocp-index, ocp-build, etc.) and more recently opam-bin and drom.
As I said, this is a work-in-progress, and there are many features that we will be adding in the next months to make this website much easier to navigate, for users to rapidely reach the information that
matters for them. We hope it will be inspirational for all the other developers who are working on similar projects, and we are looking forward to using their projects soon too!
Also for people using my packages, I’d just like to mention they may miss important documentation bits on https://docs.ocaml.pro until that issue is resolved.
We have already started looking at this issue, I hope it will be fixed very soon !
and it built me (among others) the documentation with odoc in the _build/default/_doc subdirectory that I could check (and realise that I am doing many things wrong). This is very convenient and centralised with other checks. It was discouraging at first to read that dune-release it only supports GitHub projects, but the above command worked nevertheless.
Thanks for a quick response and for your effort making it!
It all looks great indeed. I never really paid much attention to improving documentation comments in my projects because my libraries are small (so far) and I couldn’t see a point in hosting docs for them myself, while ReadTheDocs doesn’t make it very easy to deploy OCaml project docs.
Now there are no reasons not to write proper docs, and no excuses for not doing it.
dune build @fmt did not do anything for me but dune build @doc is nice too it turns out (I did not know odoc before yesterday, but it would have told me what to install). OTOH the checklist aspect of dune-release before publishing is more like what I was looking for.
Congratulations on the release and great work from your team. I have one piece of feedback: would it be possible to tie together this new site and the existing opam - Packages ?
Concretely, could a new field Documentation: be added to the package detail page e.g. opam - decimal which would point to e.g. index (OPAM.decimal.0.2.1.index) ? It might even be possible to do a simple mapping from one URL to the other so that no sophisticated package databases would need to be kept in sync?
I think it would greatly help usability (and SEO too) to be able to click through from the opam package page directly to its doc page.
