Re: lame sphinx questions [Was: lame epydoc questions]
Phlip wrote: On May 10, 1:51 pm, Phlip phlip2...@gmail.com wrote: On May 10, 1:39 pm, Chris Rebert c...@rebertia.com wrote: Sphinx is in vogue right now:http://sphinx.pocoo.org/ Okay, we have ten thousand classes to document. How to add them all to index.rst? 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. JM -- http://mail.python.org/mailman/listinfo/python-list
Re: lame sphinx questions [Was: lame epydoc questions]
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.
--
http://mail.python.org/mailman/listinfo/python-list
Re: lame sphinx questions [Was: lame epydoc questions]
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
Re: lame sphinx questions [Was: lame epydoc questions]
epydoc supports reStructured text markups. Oh, good. For a moment there, I thought I'd be stuck with a markup language that was persnickety! -- http://mail.python.org/mailman/listinfo/python-list
