sphinx-argparse-cli

Render CLI arguments (sub-commands friendly) defined by the argparse module. For live demo checkout the documentation of tox, pypa-build and mdpo.

Installation

python -m pip install sphinx-argparse-cli

Enable in conf.py

# just add it to your list of extensions to load within conf.py
extensions = ["sphinx_argparse_cli"]

use

Within the reStructuredText files use the sphinx_argparse_cli directive that takes, at least, two arguments:

For example:

.. sphinx_argparse_cli::
  :module: a_project.cli
  :func: build_parser
  :prog: my-cli-program

If you have code that creates and uses a parser but does not return it, you can specify the :hook: flag:

.. sphinx_argparse_cli::
  :module: a_project.cli
  :func: main
  :hook:
  :prog: my-cli-program

Refer to generated content

The tool will register reference links to all anchors. This means that you can use the sphinx ref role to refer to both the (sub)command title/groups and every flag/argument. The tool offers a configuration flag sphinx_argparse_cli_prefix_document (change by setting this variable in conf.py - by default False). This option influences the reference ids generated. If it's false the reference will be the anchor id (the text appearing after the '# in the URI once you click on it). If it's true the anchor id will be prefixed by the document name (this is useful to avoid reference label clash when the same anchors are generated in multiple documents).

For example in case of a tox command, and sphinx_argparse_cli_prefix_document=False (default):

• to refer to the optional arguments group use :ref:`tox-optional-arguments` ,
• to refer to the run subcommand use :ref:`tox-run` ,
• to refer to flag --magic of the run sub-command use :ref:`tox-run---magic` .

For example in case of a tox command, and sphinx_argparse_cli_prefix_document=True, and the current document name being cli:

• to refer to the optional arguments group use :ref:`cli:tox-optional-arguments` ,
• to refer to the run subcommand use :ref:`cli:tox-run` ,
• to refer to flag --magic of the run sub-command use :ref:`cli:tox-run---magic` .

Due to Sphinx's :ref: only supporting lower-case values, if you need to distinguish mixed case program names or arguments, set the :force_refs_lower: argument. With this flag, captial-letters in references will be converted to their lower-case counterpart and prefixed with an _. For example:

• A prog name SampleProgram will be referenced as :ref:`_sample_program...` .
• To distinguish between mixed case flags -a and -A use :ref:`_sample_program--a` and :ref:`_sample_program--_a` respectively

Note that if you are not concerned about using internal Sphinx :ref: cross-references, you may choose to leave this off to maintain mixed-case anchors in your output HTML; but be aware that later enabling it will change your anchors in the output HTML.