[PEAK] A small coding project for anyone desiring to contribute

[Phillip J. Eby]

I've been thinking that it would be really nice to have a "quick reference 
guide" to PEAK.

Specifically, it would be nice to have a script that could spit out, for 
any given PEAK API, a list of the names defined in that API, whether each 
name was a class or function, and a one-line description.

I'm thinking that this could be auotmated by the fairly simple process of 
doing a 'dir()' on the API module, and extracting the first line from the 
'__doc__' attribute of that object.  It would be nice if the script could 
produce both plain text (for interactive use via the "peak help" command) 
and HTML for putting up on the PEAK website.  (For extra credit, PDF would 
be handy, too.)

For the HTML and/or PDF versions, it'd be nice to actually include function 
signatures, or perhaps just links to the API reference for the item.

The initial output of the script would probably vary in quality quite a 
bit, because some docstrings probably won't have a very helpful first 
line.  However, since it's generated by a script, it would suffice for me 
to fix the docstrings that it brings to my attention, and let the script 
re-run each night.

In essence, this quick reference would provide a much-needed index for 
PEAK's online documentation.  Indeed, depending on how it worked, maybe we 
could just use it to generate text files that would be processed by 
HappyDoc during the normal documentation runs.

The problem with HappyDoc, and indeed most Python documentation tools, is 
that they don't give you a way to handle PEAK's "api" modules 
effectively.  They all want to document where the API classes and modules 
*are*, which is the exact opposite of what we want: to portray each API as 
an API.

Anyway, I just thought I'd throw this thought out there as a suggestion 
that if anybody wants to write some code for PEAK, something like this 
might be handy.  If you're interested, let me know and we can discuss 
design details further on IRC or private e-mail.