[FRPythoneers] PythonDoc review

Sean Reifschneider jafo at tummy.com
Mon Mar 27 03:45:35 MST 2000

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.

There are a few things that I think Java did right, and javadoc is one
of them.  While Python includes __doc__ strings, there aren't really
any tools for DOING anything with them.  Not something to be proud of.
Today I woke up thinking about the the problem, and found that Evelyn
had downloaded PythonDoc and Crystal.  As far as I know, these are the
only two packages available (I exclude the IDLE class browser).

The short form is that, unfortunately, neither of these tools are
really usable.  Both will definitely need work before they reach
a state where I consider them usable, though in their current forms
they can be useful to some degree.

Note that there is a standard Structured Text
(http://www.python.org/sigs/doc-sig/stext.html) for mark-up of the
doc-strings.  See the Doc-SIG (http://www.python.org/sigs/doc-sig/)
for more information.

PythonDoc (http://starship.python.net/crew/danilo/pythondoc/)

	Originally released on August 6, 1998, it's currently at version
	0.7.  It's youth shows.  It had problems with indented paragraphs
	and examples.  The output format is minimal, but does work.  I found
	it's excessive use of colors a bit irritating (pink on grey wasn't
	very readable, for example).

Crystal (http://eh.org/~laurie/comp/python/crystal/)

	I liked the output of this one the best.  This is however a 0.3
	release, and is very incomplete.  There is no tool yet for building
	the documentation, you either have to hack the samples or build
	your own based on the classes provided.
	It provides a nice index, but the hyper-links were never provided
	so one had to page through the documentation manually.  The samples
	showed links working, so this may have been an invocation problem.
	As-is however, I don't believe it's usable.

	I'd question using a Python documentation system which doesn't
	seem to include any doc strings...

gendoc (http://starship.python.net/crew/danilo/download.html#gendoc)

	This one hasn't been maintained since 1998 as far as I can tell.
	Once I hacked it to get it working, it produced reasonable output.
	The HTML output is pretty good, however references to methods within
	classes seems to be broken.  Much better structured text processing
	than PythonDoc, but still has some problems.

	Probably the most useful of the group.

On the Structured Text front, I would argue that something that is a bit
more specific to programming is a good idea.  While Structured Text 
*ALLOWS* you to make things like arguments clear to the reader, there's
no format for making them easily parsable by a class browser or
intelligent editor.

Some guideline for specifying information about the objects beyond
just a lump of text is important.  I like Structured Text's goal of
using regular text, however I think the problem needs some additional
rules for specifying exceptions generated in the code, arguments,
and return codes.

I'm left wondering why these tools aren't a higher priority.  Does no one
really use javadoc?  Could it be that once I have the tool I'll find I
don't use it as much as I expect?  Building reusable code would seem to
dictate it as a requirement, users won't likely be "fresh" on it's usage
later down the line.

 "Are you classified as human?"  "No, I am a meat popcicle."
                 -- _The_Fifth_Element_
Sean Reifschneider, Inimitably Superfluous <jafo at tummy.com>
URL: <http://www.tummy.com/xvscan> HP-UX/Linux/FreeBSD/BSDOS scanning software.

More information about the FRPythoneers mailing list