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
[email protected]
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel
