[PEAK] Option parsing prototype + new-style documentation
Phillip J. Eby
pje at telecommunity.com
Thu Nov 25 23:40:33 EST 2004
I've just checked in an almost-finished version of the new
'peak.running.options' framework, to let you do option parsing via
attribute metadata, like this:
from peak.running import commands, options
dbURL = binding.Obtain(
metavar="URL", help="Database URL")
It's not actually integrated with the 'commands' framework yet, so the
'_run()' method of the above class would have to do something like:
args = options.parse(self, self.argv[1:], description=self.usage)
in order to set its attributes from the provided options, and to receive
the non-option arguments in 'args'.
Included in the check-in is some *extremely* in-depth documentation, chock
full of examples. It's written in reStructuredText format, so if you have
the docutils package you can create a nice hyperlinked HTML version for
more convenient reading. (Or a PDF, or whatever other format you might
like, that docutils supports.)
I would be very interested in any feedback that anyone has about the format
or content of the documentation. This is the direction I'd like to move in
for future PEAK documentation and unit tests. That is, writing them in
reStructuredText and processing them with doctest to verify the examples,
thus ensuring that every feature has one or more known-working examples.
So, if there are any issues with the comprehensibility or usability of the
docs I'm doing in this format, I'd like to know. Currently, there are four
such documents in PEAK:
* peak.running/options.txt -- the doc I described above
* peak.binding/attributes.txt -- work in progress, describes the metadata
framework and attribute initialization API, but should eventually grow to
encompass all attribute-related features of peak.binding.
* peak.util/unittrace.txt -- a somewhat more polished document explaining
the peak.util.unittrace module.
* dispatch/combiners.txt -- work in progress, currently describes only the
MapCombiner base class, but should eventually grow to encompass all
method-combining features of the PyProtocols dispatch package.
So, if you get a chance, please take a look at some of the above, more or
less in the order shown, and let me know what you think. Thanks.
More information about the PEAK