For a number of packages I’ve been using via opam, I’ve been manually reading the documentation comments in the .mli files on github or the like.
It only now occurred to me that this is somewhat strange — that is to say, I’m manually reading ocamldoc documentation comments in a package’s source code, even though there’s supposed to be a mechanism that turns such comments into a nicely formatted page to read.
How is one supposed to be reading the documentation for packages?
Some projects on github utilize github pages to host the generated (via odoc, etc.) docs. Take ocaml-cohttp’s API documentation for example, the link to which is available at the bottom of the README.
You can also utilize @dbuenzli’s cool odig tool to generate your installed/pinned packages’ docs locally. It’s as simple as:
opam install odoc ocaml-manual odig
odig odoc # Generate the docs
odig doc # Open your browser to browse the local docs
odig doc <package-name> # Open the docs of <package-name>
What’s great with odig is that it can reference other packages, so navigating between dependent packages is so easy.
The good news is there seem to be works on having a centralized docs host (e.g. docs.ocaml.org) so that docs are going to be easily accessible.
@bobbypriambodo is right, but at present there are some packages with which odoc has trouble. Sometimes the documentation is only partially generated. (It’s my understanding that this is a temporary problem.)
In some packages, it’s possible to generate the docs using make doc or jbuilder build @doc (if the package uses jbuilder) or ocaml setup.ml -doc (if the package uses oasis). This may work better if odoc doesn’t fully succeed with the package. Then the docs will be somewhere under the root of the project. This might require getting the source distribution. There may be a way to do this somewhere under .opam without downloading the source tree independently.
There’s a line in the opam package files that specifies how to build documentation, but I can’t tell if opam does that? It certainly doesn’t seem to always put the documentation into the directory under .opam, but I haven’t checked if that is just that making the docs is broken for the couple of packages I checked…
Yes, this is mostly work in progress. odig is nice, and hopefully we’ll have comprehensive online documentation soon. My quick solution is to use ocp-browser: although not perfect for all purposes (no per-library view of modules), it doesn’t require any extra build effort and allows you to browse interfaces+doc easily. It’ll automatically browse your installed interfaces (press <space> to show the doc, when cmt(i) files are available).
I also go with ocp-browser, best productivity tool for me when it comes to ocamldoc browsing.
Do you know if it’s possible to make ocp-browser display functors in a useful way?
It isn’t, unfortunately. I agree it would be very nice.