Phlip wrote:
On May 11, 3:54 am, Jean-Michel Pichavant <jeanmic...@sequans.com>
wrote:
I remember trying using Sphinx for auto documented APIs, but it was not
suitable at that time. You can include API docs generated from the code,
but you still need to write the docs around.
If I'm correct, Sphinx is one of the best tool to document public APIs.
However to build internal documentation with everything from interfaces
to implementations, epydoc is still the best, it builds everything with
no additional writing, just press the button.
Ah, thanks. We are all about writing '''doc strings''', then ripping
them to form documentation that we DO intend someone to READ and USE!
Now the problem with epydoc is it uses a persnickety text markup
language that...
- throws a syntax error & reverts to <pre> when the wind blows
- demands all kinds of extra markup, such as @param
- uses >3 different kinds of escapes, @, L{}, & <html>
- has no developer tests to speak of
I'm all about cross-linking and transcluding, and I wanted to upgrade
epydoc to do it, so I need to make sure that all those issues are
going to be either worth our time to fix or work around, and I didn't
overlook some better system.
epydoc supports reStructured text markups. AFAIK it's still the best doc
builder available for python code. Too bad it is not maintained since 2
years and the 3.0 release.
If there was any effort to provide however, I think it would be on
sphinx so it would allow building the complete doc from python code. As
written in the doc, it's currently half-automated.
JM
--
http://mail.python.org/mailman/listinfo/python-list
