[PEAK] Option parsing prototype + new-style documentation

[Ulrich Eck]

Hi Phillip,

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.

cheers Ulrich

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(
>              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.
> 
> _______________________________________________
> PEAK mailing list
> PEAK at eby-sarna.com
> http://www.eby-sarna.com/mailman/listinfo/peak
-- 
--------------------------

Ulrich Eck
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