On Fri, Mar 14, 2008 at 10:43:08AM -0700, Neal McBurnett wrote:
> I'm trying to do nice clean documentation for a python script I run
> from the command-line, and I'd like pydoc or a similar program to
> document it well. But I don't want to duplicate option information by
> putting it both in my docstring and in optparse.
>
> I would think that pydoc might notice an OptionParser instance at the
> module level and show the options defined there, but it doesn't seem
> to. Would it be hard to add to pydoc? Do any other documentation
> programs do that?
For now I've instead put this quasi-template-tag in my docstring in
an appropriate place: %InsertOptionParserUsage%
and added this code to the module to incorporate the usage into the
docstring after it is defined:
# incorporate OptionParser usage documentation in our docstring
__doc__ = __doc__.replace("%InsertOptionParserUsage%\n", parser.format_help())
That gets me pretty close. The biggest problem is that when pydoc
prints it, the usage statement starts with "Usage: pydoc [options]"
rather than "Usage: myprogram [options]". I could set the
OptionParser "prog" option to override that, but I prefer that in real
life the program provide usage referencing sys.argv[0] rather than
hard-coding it, in case it gets deployed under a different name.
Comments?
Neal McBurnett http://mcburnett.org/neal/
___
Tutor maillist - Tutor@python.org
http://mail.python.org/mailman/listinfo/tutor
