Sphinx for API documentation

[melevine at gmail.com]

On Mar 5, 5:38 pm, Robert Kern <robert.k... at gmail.com> wrote:
> On 2009-03-05 19:23, Paul Hildebrandt wrote:
>
> > Thanks, I've been playing with that but I believe it assumes a reST
> > structure you build, then use autodoc to bring in your code's
> > docstrings.  I would rather not hand generate the main reST
> > structure.  I am hoping to use Sphinx like Epydoc and just run it on a
> > code base and have it generate the API documentation.
>
> Sphinx will probably never grow the ability to do that for you. Using epydoc as
> a library to collect docstrings (or just locate documentable objects) is
> certainly doable, though. You can use that information to construct the reST (or
> just the reST structure with autodoc commands) for Sphinx to generate
> nice-looking docs.
>
> --
> Robert Kern
>
> "I have come to believe that the whole world is an enigma, a harmless enigma
>   that is made terrible by our own mad attempt to interpret it as though it had
>   an underlying truth."
>    -- Umberto Eco

I don't think Sphinx necessarily needs to support it as much as we
need something to write reST in a Sphinx friendly way.  It would be
cool to get epydoc to spit out to a Sphinx reST format (since Sphinx
does have /some/ special keywords for reST).  The Sphinx html is so
much richer and more flexible than the standard epydoc (IMHO).  It
would seem prudent to add a plugin to epydoc or docutils or something
for that specific purpose, if not to just spit out standard reST.
Though I don't even know if those modules/services are flexible enough
to do that.

Sphinx should stay a hand written thing but the ability to
automatically generate API documentation and then layer your own hand
written documentation ontop of it is also an attractive feature.
Sphinx has this to some extent with automodule and autoclass, etc.
But they don't provide the functionality I think a lot of people
want.  Even with automodule you have to add an autoclass line every
time you add a class to a module.  So to me automodule is a misnomer.