The state of Ocamldoc and Odoc

@xvw I think such customisation is an option in the future, but right now it would be useful to get contributions on the basic default stylesheets. For instance, http://docs.mirage.io has a number of libraries represented now, and looking through the docs and fixing up stylesheet issues for some layouts (or reporting the bugs on https://github.com/ocaml-doc/odoc/issues with links to the problem HTML) would be most useful.

That would help us get to a really solid odoc release that is a viable replacement for ocamldoc HTML out of the box, without any customisation being needed. It’s fairly urgent to get there now, as ocamldoc is increasingly showing its age and not supporting new OCaml features due to a lack of active maintenance (ppx is particularly problematic at the moment with ocamldoc, from what I can tell).

1 Like

Hum I’ve answer with a private-message, sorry for that.
Is there a “easy-way” to generate locally docs.mirage.io (or the janestreet doc) to write some experiments on the css ?

Yes. opam pin odig --dev && odig odoc && odig doc

1 Like

opam pin add odig --dev && odig odoc && odig doc I suppose ?
Thanks a lot !

The complete build chain for docs.mirage.io can also be reproduced via this Dockerfile (from which the live site is generated):

https://github.com/mirage/mirage/blob/master/Dockerfile.doc

2 Likes

New release if you want to get rid of the pins. See [ANN] Odig 0.0.2

Is there an ocamlbuild-odoc plugin to replace ocamlbuild’s doc-production rules with odoc? Do you think that having such a plugin would help odoc’s adoption? (I know that odig does this well, but maybe a less packaging-invasive way to “switch to odoc” for people that explicitly build their own documentation could help.)

Not that I’m aware of. [quote=“gasche, post:13, topic:244”]
Do you think that having such a plugin would help odoc’s adoption?
[/quote]

Could be a good idea. Currently non-jbuilder topkg still uses ocamldoc to produce the documentation which is pushed on topkg publish.

It would be nice if we can always use a single documentation tool. Especially with https://github.com/ocaml-doc/odoc/issues/27 in mind so that you can check your package cross-links are correct without having to pin and odig.

There is a Jbuilder odoc rule now in the development release; see https://github.com/janestreet/jbuilder/pull/74, so one for ocamlbuild also makes sense.

An interesting aspect of the Jbuilder support is that the multi-project build feature in Jbuilder lets you clone several repositories and build cross-references docs for them in one pass. OCamlbuild doesn’t quite the same architecture, so documentation would necessarily be local versions for that particular package. Still useful to have, but less compelling than just running odig to build the docs for all installed packages.

Is there a decentralized workflow to get cross-reference working, today or planned? Each project could have in its metadata on where its documentation is uploaded (which can be set by default to “wherever the big doc repository of all opam-repository packages are”), and when building a project’s documentation locally odoc could check that information up to generate links to the right place for each external module.

1 Like

I think the problem is that you really need the .odoc files for that to actually work. It’s not just about having a root href to point to. But I may be wrong @trefis knows that in detail.

D

Note that if I’m wrong that would be easy to achieve via an opam v2 x-field that can be looked up in package installs.

What’s the benefit of this approach though? Right now the decentralised approach is to simply install the cmt[i] files (which have all the documentation and parsetree metadata), and to do a single pass to generate the documentation.

So an individual package could generate HTML for its own code, in the ocamldoc style, without cross references. But if it installs the cmt[i] files, then a global generator like odig can also generate cross-referenced docs.

My understanding of the ocamlbuild plugin is that it would replace the functionality of ocamldoc for a single repository, and I think that can be done today. For the new cross-referencing functionality, I believe the right place for that is in something that can manage a batch of modules, which today is opam+odig, or jbuilder+workspaces.

I think you or I misunderstood what @gasche was suggesting.

If I understood him well this is rather for people who gen their documentation and publish it somewhere on the www (like many packages do) so that external links go from to your www to the one of the others. For local installs of course properly installing your cmt[i] files is the way to go.

This is what I want. I’ve been discussing/planning this on and off, but I don’t have time to implement it right now.

TBH I don’t think that’s easily achievable. Take for example the title splicing that occurs when your refer to the id of the section of another package via the {!pkg.M.secid} directive.

Also while nowadays it is easy to do an odig online-doc PKG to get to the particular docs a package PKG may publish online I think there’s more value in having a docs.ocaml.org in the vein of docs.mirage.org that centralizes the docs of packages published on the opam repo (for discussing online) and the odig approach that makes you a local doc set for the packages you have installed and are presumably interested in.

Would docs.ocaml.org exist I wouldn’t mind no longer publishing API docs on my website and relagating that to the packaging infrastructure.

1 Like

Ah that makes sense too. I view that as a second, more complex step after we get a central docs.ocaml.org working. The reason is package versions: odoc needs a consistent view of the dependencies (just like the normal OCaml compiler cannot mix and match compiled interfaces). Everyone who is publishing docs will need to agree on their dependency chain versions and ensure they are exactly the same. This is possibly solvable in odoc, but it seems like a complex new feature, and so I’d rather focus on publishing the centralised documentation first.

I’d rather focus on publishing the centralised documentation first.

Do we have any concrete plans for this yet? I know that everyone who knows the ins and outs of CI and consistent package universes is very busy, but maybe if we had a clear picture of what was needed we could get some help from the community. Or is it mostly about setting up the necessary hardware?

Quick question,
How can I “compile” a complete package using odoc ?
For example, for olmi I’m trying to run : odoc compile _build/lib/olmi.cmt, but I have to build all of the internal modules of the package, and odoc could not generate an index for the package.

Edit : What I understand is that it requires an .mld file, But after some searches, I can not find the form of the .mld file: /, I naively tried:

odoc-v1.1.1
Olmi
OlmiInterfaces
OlmiMake

That may be a little bit long to answer is certainly still in flux. You may want to try to follow this function which is the way odig does it.

1 Like