[Doc-SIG] autogenerating API docs using sphinx
Ondrej Certik
ondrej at certik.cz
Tue Apr 15 01:34:21 CEST 2008
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
More information about the Doc-SIG
mailing list