[Doc-SIG] autogenerating API docs using sphinx

[Ondrej Certik]

On Tue, Apr 15, 2008 at 12:20 AM, Gael Varoquaux
<gael.varoquaux at normalesup.org> wrote:
> 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.

Thanks Gael for sharing it with us. I looked at it and it looks really great!

I want a code, that goes through all modules (or files) and produces
API doc for each function and each class + methods it finds. When I
have some time, I'll try to look at your code and see if I can reuse
something.

Ondrej