[ANN] docs.ocaml.pro : an OCaml Documentation Hub

Hi,

We are pleased to announce that we just published the first version
of the OCaml Documentation Hub on:

https://docs.ocaml.pro

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.

We welcome feedback and contributions!
Enjoy !


The OCamlPro team

65 Likes

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. :100:

12 Likes

Great work on this site, and I love the domain name as well :wink:

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.

23 Likes

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.

16 Likes

This is going to be very useful, congratulations.

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?

3 Likes

Dune-release does a series of automated checks and more :slight_smile:

Congratulations, this is truly fantastic! This is honestly a best-of-breed implementation of any docs site I’ve seen. Beautiful, comprehensive, and fast!

Some quick feedback:

  • I can’t find my own library in there, even though it’s on opam: opam - tablecloth-native
  • 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

Well done again!

5 Likes

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.

6 Likes

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!

5 Likes

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 !

4 Likes

It’s all very intriguing, but the docs.ocaml.pro site seems down now.

Thanks for the pointer. I tried:

dune-release distrib

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.

1 Like

It’s all very intriguing, but the docs.ocaml.pro site seems down now.

Indeed, the website was taken down by mistake, the problem has been fixed now…

FWIW, a dune build @fmt achieves this as well. :slight_smile:

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.

3 Likes

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.

ah yes sorry, I thought about dune build @doc and typed @fmt.

I use --watch mode when writing docs nowadays, for something approaching a live docs workflow:

; dune build @doc --watch --terminal-persistence=clear-on-rebuild

Doesn’t quite get as far as updating my browser dynamically, but it’s close.

4 Likes

This might help with browser refresh: live-server - npm

I haven’t used it myself.

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.

4 Likes