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.
Answers:
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.
Use sphinx-argparse extension:
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
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.
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.
Use sphinx-argparse extension:
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