[Doc-SIG] autogenerating API docs using sphinx

[Georg Brandl]

Ondrej Certik schrieb:
> On Sun, Apr 20, 2008 at 11:47 AM, Georg Brandl <g.brandl at gmx.net> wrote:
>> Ondrej Certik schrieb:
>>
>>
>> > Hi,
>>  >
>>  > 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.
>>  >
>>  > Unfortunately, if the docstrings are not written in rst, it's not
>>  > going to work properly. Also it uses python inspection (it's easy to
>>  > implement), instead of parsing the source files directly.
>>  >
>>  > I am putting it here in case you find it useful. I wrote it for sympy
>>  > originally, but we are not using it yet, because the output contains
>>  > too much noise.
>>  >
>>  > Please let me know if you improve it/fix it. :)
>>
>>  What does it do differently from autodoc, and could autodoc be extended
>>  to cover your usecase as well?
> 
> You mean autodoc in sphinx?

Yes.

> I want to get a documentation of all classes+methods and functions in
> all files in sympy automatically (we have a lot of .py files and I
> don't want to handle each of them manually). I didn't figure it out
> how this could be done in autodoc. But if you look at my script, it's
> really simple, so the autodoc definitely can be extended.
> 
> But the script currently produces quite a lot of noise (some empty
> classes, etc.) in the output. It needs to be improved.

autodoc needs currently at least one entry per module in some file.
It does everything else your script does, as far as I can see.

Georg


-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.