[Doc-SIG] Automated __doc__ string processing systems

[Dinu Gherman]

"Edward D. Loper" wrote:
> 
> I'm pretty new to the area, but as far as I can tell there are
> 3 such tools currently in active development:
>   * Happydoc
>   * Pydoc
>   * Docutils

You may want to add one more effort to your list that, for the 
lack of a better name, so far is called "docpy". It is in some-
thing like an embryonal form (which is why most likely you don't 
know about it) and comes with the current release of the Report-
Lab package (inside the libs directory). See here if you want to
give it a try (The current version is named docpy0.py. There is 
also one labelled docpy1.py, but this is *very* experimental and 
you probably don't want to touch that, yet.):

   http://www.reportlab.com/
   ftp://ftp.reportlab.com/current.zip

Naturally, all authors are handling partly different require-
ments. ReportLab's are to generate electronic/print documenta-
tion for modules/packages that is not necessarily interactive,
but should serve to make customers understand what is being
delivered and, ideally, how to use it.

docpy builds on inspect and does generate several formats, 
like ASCII, HTML and PDF (with slithly varying quality). It
seems to implement some of the functionality that pydoc now
apparently has implemented as well, but in a rather different
manner.

It's too early to make grand announcements, but the focus of
docpy is basically that of extensibility. A good example of 
what I mean is a module named graphicsdoc (also part of the
current distribution in the lib directory) that is built on
top of docpy and that serves as a tool to build a catalog of
widgets and charts from the upcoming ReportLab charting sub-
package.

Well, this is just to name another effort, not to discourage
you or anybody to continue working on her own. Ideally, one
day some of these approaches will merge again where the philo-
sophy and feature set allows to do that. Hopefully, there'll 
be some very informal meeting about this here in the conferen-
ce hotel...

Kind regards,

Dinu

-- 
Dinu C. Gherman
ReportLab Consultant - http://www.reportlab.com
................................................................
"The only possible values [for quality] are 'excellent' and 'in-
sanely excellent', depending on whether lives are at stake or 
not. Otherwise you don't enjoy your work, you don't work well, 
and the project goes down the drain." 
                    (Kent Beck, "Extreme Programming Explained")