Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Python: Python

Sphinx for API documentation

 

 

Python python RSS feed   Index | Next | Previous | View Threaded


paul_hildebrandt at yahoo

Mar 5, 2009, 9:23 AM

Post #1 of 7 (3918 views)
Permalink
Sphinx for API documentation

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
--
http://mail.python.org/mailman/listinfo/python-list


benjamin at python

Mar 5, 2009, 12:21 PM

Post #2 of 7 (3807 views)
Permalink
Re: Sphinx for API documentation [In reply to]

Paul Hildebrandt <paul_hildebrandt <at> yahoo.com> writes:

>
> 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.




--
http://mail.python.org/mailman/listinfo/python-list


andrew at acooke

Mar 5, 2009, 12:30 PM

Post #3 of 7 (3809 views)
Permalink
Re: Sphinx for API documentation [In reply to]

Benjamin Peterson wrote:
> Paul Hildebrandt <paul_hildebrandt <at> yahoo.com> writes:
>> 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.

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.

andrew


--
http://mail.python.org/mailman/listinfo/python-list


benjamin at python

Mar 5, 2009, 1:22 PM

Post #4 of 7 (3814 views)
Permalink
Re: Sphinx for API documentation [In reply to]

2009/3/5 andrew cooke <andrew [at] acooke>:
> Benjamin Peterson wrote:
>> Paul Hildebrandt <paul_hildebrandt <at> yahoo.com> writes:
>>> 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.
>
> 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



--
Regards,
Benjamin
--
http://mail.python.org/mailman/listinfo/python-list


paul_hildebrandt at yahoo

Mar 5, 2009, 5:23 PM

Post #5 of 7 (3811 views)
Permalink
Re: Sphinx for API documentation [In reply to]

On Mar 5, 1:22pm, Benjamin Peterson <benja...@python.org> wrote:
> 2009/3/5 andrew cooke <and...@acooke.org>:
>
> > Benjamin Peterson wrote:
> >> Paul Hildebrandt <paul_hildebrandt <at> yahoo.com> writes:
> >>> 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.
>
> > 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. Seehttp://sphinx.pocoo.org/ext/autodoc.html
>
> --
> Regards,
> Benjamin

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
--
http://mail.python.org/mailman/listinfo/python-list


robert.kern at gmail

Mar 5, 2009, 5:38 PM

Post #6 of 7 (3808 views)
Permalink
Re: Sphinx for API documentation [In reply to]

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

--
http://mail.python.org/mailman/listinfo/python-list


melevine at gmail

Mar 5, 2009, 8:06 PM

Post #7 of 7 (3805 views)
Permalink
Re: Sphinx for API documentation [In reply to]

On Mar 5, 5:38pm, Robert Kern <robert.k...@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.
--
http://mail.python.org/mailman/listinfo/python-list

Python python RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.