[FRPythoneers] PythonDoc review

Uche Ogbuji uche.ogbuji at fourthought.com
Mon Mar 27 10:10:37 MST 2000


Sean Reifschneider wrote:

> Python documentation generators have been something that I've
> been interested in since I started using the language, but haven't really
> pursued any further than building some class browser functionality.
> The conversation at the last FRPythoneers meeting reminded me of
> this lack.

<snip>

A quick and huge "amen" to your rant, Sean.  I've witnessed the debacle
at first hand.  Fred Drake invited me to join the doc sig as they were
on their big push to get in a python doc standard by IPC8.  I promptly
proposed that we mostly rip-off javadoc for in-line documentation and
use this information and other supplied data to generate Docbook for
programmer guides.  This and other such simple proposals have been
pretty much drowned out by a chorus of very arcane and complex ideas,
many of which seem like the inventions of entirely new languages for
Python documentation.

A lot of us lave left the SIG in bewilderment, and I wonder whether we
can ever expect a simple and effective standard to be "blessed" by Guido
any time soon.  In the meantime fourthought has moved to Docbook for
on-line docs and is considering a Javadoc (with a few good ideas from
Structured Text) approach for in-line docs.

-- 
Uche Ogbuji
Fourthought, Inc., IT Consultants
uche.ogbuji at fourthought.com	(970)481-0805
Software-engineering, project-management, knowledge-management
http://Fourthought.com		http://OpenTechnology.org





More information about the FRPythoneers mailing list