[PEAK] Option parsing prototype + new-style documentation

[Phillip J. Eby]

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(
             PropertyName('myapp.dburl'),
             [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.