[Tutor] pydoc introspecting info via OptionParser?

[Neal McBurnett]

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/