Re: [MirageOS-devel] API documentation best practices

[Richard Mortier <richard.mortier@xxxxxxxxxxxx>]

On 3 June 2015 at 16:57, David Scott <scott.dj@xxxxxxxxx> wrote:
...
>
> 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?

+1 to both those suggestions -- would definitely want multiple
versions of docs, with an auto-updated "latest" or similar if
possible.

Note that the ocaml-travisci-skeleton scripts are moving toward being
.ml files rather than pure scripts-- the sh front-ends now simply pull
the necessary bits, install ocaml, and then build and execute their
.ml counterpart. The .travis-mirage.ml contains the usual boilerplate
for pushing build outputs back to Travis (per the various website
examples). Ought to be straightforward to extend to also push doc
build output.  Would be useful to get some standard "good practice"
examples of doing doc builds though.

> 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?

That'd be nice, but I'd settle for up-to-date docs with reasonable
coverage to start with :)

-- 
Richard Mortier
richard.mortier@xxxxxxxxxxxx

_______________________________________________
MirageOS-devel mailing list
MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel