Re: [MirageOS-devel] API documentation best practices

[Drup <drupyog+caml@xxxxxxxx>]

> 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
MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel