A few months ago I saw the announcement of the release of odoc.
Until now, I used exclusively OCamldoc because it was pretty well documented and usable out-of-the-box. (And with one of the @dbuenzli 's style sheets, it can be pretty beautiful).
Recently, I questioned my “good practices” (moving from Oasis to Jbuilder for example), but it seems that Odoc is not valid for OCaml 4.04.
In addition, Odoc does not appear to be documented.
The question I ask myself is “is Odoc intended to become a standard for generating OCaml documentation”? And what are the best ways to contribute (eg by creating a layout?)
There was a new release of odoc with 4.04 support yesterday. I’m not sure it’s made its way on to opam yet.
In addition, Odoc does not appear to be documented
Yeah, I wouldn’t say that odoc is ready to be used directly by users as it’s not yet documented and the interface is still being finalised. However, there is support for it in jbuilder and odig which are both documented and ready to use.
For example, these pages are generated using odig:
Is there a way to create custom generators (or extend specifics generators (ie HTML)) ? Should I check the doc-ock-html repo ?
There is no support for custom generators. The intention is to produce HTML that is easy to style using CSS, and let people provide there own stylesheet.
For now we only support an HTML backend. In the future we’ll probably support a few others. I doubt we’ll provide direct support for custom backends, although you could probably write something that read odoc files and generated output from them.
Hum, it is maybe the best approach to avoid some kind of complexity !
But, is there a possibility to specifies custom layout/file-structures ? For example, if I will create a search-bar using JavaScript ?
@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).
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 ?
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.)
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.
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.
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.