[Doc-SIG] autogenerating API docs using sphinx

[Gael Varoquaux]

On Mon, Apr 14, 2008 at 11:51:32PM +0200, Ondrej Certik wrote:
> I wrote a short script for autogenerating API from sources, the output
> are .rst files that sphinx can parse and generate the docs in the
> modules/index sections.

I just did something similar this week end.

I would like to get it in our SVN, but first Georg needs to implement a
missing directive in the LaTeX writer, because I can't commit my changes
to SVN as long as we can't build PDFs. So to allow people to have a look
at it, I have uploaded the whole documentation directory to
http://gael-varoquaux.info/docs.tar.gz , including the generated rest,
and the html. The two interesting files are render_image.py, which is
kind of pushing the notion of doctests to something with a graphical
output (this is for a 3D plotting application), except that it doesn't
check the output is valid yet, and "mlab_reference", which is an attempt
to make something quite general.

This is very taylored toward the documentation of mlab (a scripting API
for the plotting application). In mlab the docstring are partially
generated automaticaly, with addition of the keyword arguments, so I
could control them well to be good rest. In addition mlab is a namespace
that exposes functions to the users coming from different module, each
giving different fonctionnality. I use this to structure the
documentation.

I am not entirely happy with the code, as there might be to much code
specific to my use. I would like to see some thing like this quite
general, but I also want to keep the high quality output this gives me.
Anybody is welcomed to adapt it to your purposes, while trying to keep it
general, and we can see what comes out of it.

Cheers,

Gaël