lame sphinx questions [Was: lame epydoc questions]

Tue May 11 09:27:18 EDT 2010

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.