lame sphinx questions [Was: lame epydoc questions]

Tue May 11 10:04:19 EDT 2010

Phlip wrote:
> On May 11, 3:54 am, Jean-Michel Pichavant <jeanmic... at 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