[PEAK] A small coding project for anyone desiring to contribute
Phillip J. Eby
pje at telecommunity.com
Wed Sep 22 00:46:38 EDT 2004
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
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.
More information about the PEAK