1

All I can find is this reference:

Is it possible to use POD(plain old documentation) with Python?

which looks like you have to generate a whole separate set of docs to go with code.

I would like to try Python for making cmdline utils, but when I do this with Perl I can embed the docs directly in the source, and use the Pod2Usage module along with Getopt so that any of my scripts can be run like this:

cmd --man

and this triggers the pod system to dump documentation that is embedded in the script in man-page format. It can also generate shorter (synopsis), or medium formats.

It looks like I could use the pydoc code and kind of reverse engineer it to sort-of do the task (at least showing the full documentation), but I am hoping something better already exists.

Community
  • 1
  • 1
Tony K.
  • 5,535
  • 23
  • 27

2 Answers2

2

The python-modargs package lets you create self-documenting command line interfaces. You define a function for each command you want to make available, and the function's docstring becomes the help text for that function. The function's keyword arguments become named arguments and python-modargs will parse inline comments after the keyword arguments to be help text for that argument.

I use python-modargs to generate the command line interface for dexy, here is the module which defines the commands: https://github.com/ananelson/dexy/blob/027954f9234363d506225d40b675b3d6478994f4/dexy/commands.py#L144

You need to implement a help_command method to get the generated help, it's a 1-liner.

Ana Nelson
  • 36
  • 3
  • Thanks, that is exactly what I was looking for. It is also good you included an example, as I never would have found it given the lack of docs on the module page! – Tony K. Nov 11 '12 at 01:59
0

I think pydoc may be what you're looking for.

It certainly isn't quite the same as POD, as you have to call pydoc itself (e.g. pydoc myscript.py), but I guess it can be a good starting point.

Of course, you can always add pydoc support for your script by importing from it and using it's functions/classes. Checkout pydoc's own cli implementation for the best example.

Gonzalo
  • 4,145
  • 2
  • 29
  • 27