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.

Unrelated, but might be helpful. Check plac package on PyPI. — Mikko Ohtamaa, Jun 04 '12 at 21:58
Don't think it helps me with this, but interesting, thanks for the heads-up. — jeremiahbuddha, Jun 04 '12 at 22:55

score 29 · Answer 1 · answered Sep 05 '13 at 10:54

29

Use sphinx-argparse extension:

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

answered Sep 05 '13 at 10:54

ribozz

576
5
8

1

Excellent. Is there a way to have the "usage" block treated differently? For me, having it as a literal block isn't quite right. – orome Jan 21 '14 at 21:43
1

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. – orome Jan 21 '14 at 22:26

bmu · Accepted Answer · 2012-06-06T11:55:58.870

18

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.

edited Jun 06 '12 at 11:55

answered Jun 05 '12 at 08:19

bmu

35,119
13
91
108

score 8 · Answer 3 · answered Aug 09 '16 at 02:37

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

Sphinx and argparse - autodocumenting command line scripts?

3 Answers3

Linked

Related