Sphinx and argparse - autodocumenting command line scripts?

Question

I'm building a Python package, and using Sphinx to create the docs. Aside from my package code, I also include a lot of command line Python scripts, which use argparse. I was wondering if there is a way to get Sphinx to autodocument these scripts? The end goal would be a pretty-printed list of scripts, with the associated help print, arguments and options. And to be clear, I'm looking for a pre-existing way to do this, not a way to implement this myself.

This isn't as specific of a question as I usually ask on S.O., if there is a more appropriate S.E. site to post this question, let me know.

Staunch

Unrelated, but might be helpful. Check plac package on PyPI. – Lakeishalakeland

Don't think it helps me with this, but interesting, thanks for the heads-up. – Staunch

Answer 1

You can use sphinxcontrib.programoutput to include the help messages from the command line in your documentation.

This is not specific to argparse but can be used to document any script printing help messages to the command line.

Vengeance

Answer 2

Use sphinx-argparse extension:

http://sphinx-argparse.readthedocs.org/en/latest/

Happen

Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right. – Roseannroseanna

And while I'm at it, it would be nice of the output for options matched what .. option:: produces: flags only (no default indicated), aligned all the way to the left with less indentation for the description, and changing the first letter to caps and adding a period at the end if one is not already there (since the idiom for --help is to omit these and use all lowercase). Also perhaps flag entries that match the help help output more closely (e.g. -cols [COL [COL ...]] rather than just cols), since all the text is written in that context. – Roseannroseanna

Answer 3

You can use sphinxcontrib.autoprogram. pip install sphinxcontrib-autoprogram, then put

extensions += ['sphinxcontrib.autoprogram']

in your conf.py. To document command cli.py by importing cli with the argparse parser object parser (which can be a Python expression, like a function get_parser()), use

.. autoprogram:: cli:parser
   :prog: cli.py

Shenitashenk