[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [MirageOS-devel] API documentation best practices

I'd like to gather together ideas for improvement and links to examples of good API documentation, which we could try to emulate.
Very basic ocamldoc+ocamlbuild/oasis things:

This line is (imho) mandatory in every project: https://github.com/Drup/LILiS/blob/master/_oasis#L221

It is possible to also generate html page for the .ml files (option -keep-code) in a "literate programming" fashion, but it's not very usable at the moment.

It is also possible to provide an index page manually instead of the default one. I usually use this facility to provide a tutorial. Here is an ocamlbuild rule for that: https://github.com/Drup/LILiS/blob/master/myocamlbuild.ml#L80-L84

For the rest, and in particular functors, :codoc hype:

As another example Simon Beaumont (cc:d) pointed me at his ocaml-pci library[1] which rebuilds the ocamldoc from travis and auto-uploads to github pages[2]-- is this the kind of thing we should attempt to standardise, say by adding support for it into the common boilerplate ocaml-travisci-skeleton scripts? Perhaps we should embed the version in the URL so we could publish multiple versions simultaneously?
I have a very similar setup in LILiS: https://github.com/Drup/LILiS/blob/master/.travis-ci.sh It was mostly based on the (very useful) blog post about mirage kernel automatic building.

I confirm it works very well. It has the added nicety that CI will yell if the documentation generation get broken. :) Ideally, a level of automation could be added to save the documentation when a version is tagged.

I'm also a big fan of the iocamljs notebooks (e.g. the coolest notebook ever[3]). It would be really nice to write tutorials for each library to complement the API reference. Perhaps the notebooks should also be regenerated by the CI?
Yes, I wanted to do that but never got around doing it. That would be useful.

MirageOS-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.