Sphinx for API documentation

[Paul Hildebrandt]

I really like the look of Sphinx BUT I want autogenerated
documentation like Epydoc/doxygen. Does anyone know of a frontend for
Sphix that will make it work like Epydoc?

Paul

 

[Benjamin Peterson]

I really like the look of Sphinx BUT I want autogenerated
documentation like Epydoc/doxygen. Does anyone know of a frontend for
Sphix that will make it work like Epydoc?

There's a Sphinx extension called autodoc which should help you.

 

[Benjamin Peterson]

i am only vaguely remembering here, but iirc that helps you generate
something rather like python's own documentation for classes.  it's
nothing like as complete as epydoc.  i was in the same situation and ended
up using both.  you can link back + forth without too much bother.  it's a
bit of an aesthetic shock (to put it politely) going from sphinx to
epydoc, but it's a lot more useful for someone who wants to see source
etc.

Basically it lets you use reST in docstrings. See
http://sphinx.pocoo.org/ext/autodoc.html

 

[Paul Hildebrandt]

Basically it lets you use reST in docstrings. Seehttp://sphinx.pocoo.org/ext/autodoc.html

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.

Paul

 

[Robert Kern]

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

 

[melevine]

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.