[PEAK] Option parsing prototype + new-style documentation
ueck at net-labs.de
Fri Nov 26 05:15:58 EST 2004
i've used doctests in z3 development already and i like this way of
writing and using documentation/tests very much.
options.txt is written very well and having lots of these snippets will
give really good developer docs imho.
On Fri, 2004-11-26 at 05:40, Phillip J. Eby wrote:
> 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
> class MyClass(commands.AbstractCommand):
> dbURL = binding.Obtain(
> [options.Set('--db', type=str,
> 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.
> PEAK mailing list
> PEAK at eby-sarna.com
net-labs Systemhaus GmbH
CEO & Code-Artist
Ebersberger Str. 46
85570 Markt Schwaben - Germany
eMail: ueck <at> net-labs.de
phone: +49 8121 4747 10
fax: +49 8121 4747 77
More information about the PEAK