Skip to main content

render CLI arguments (sub-commands friendly) defined by argparse module

Project description

sphinx-argparse-cli

PyPI PyPI - Implementation PyPI - Python Version PyPI - Downloads PyPI - License check

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

installation

python -m pip install sphinx-argparse-cli

enable in your 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:

Name Description
module the module path to where the parser is defined
func the name of the function that once called with no arguments constructs the parser
prog (optional) the module path to where the parser is defined
title (optional) when provided, overwrites the <prog> - CLI interface title added by default and when empty, will not be included
usage_width (optional) how large should usage examples be - defaults to 100 character
group_title_prefix (optional) groups subsections title prefixes, accepts the string {prog} as a replacement for the program name - defaults to {prog}
group_sub_title_prefix (optional) subcommands groups subsections title prefixes, accepts replacement of {prog} and {subcommand} for program and subcommand name - defaults to {prog} {subcommand}

For example:

.. sphinx_argparse_cli::
  :module: a_project.cli
  :func: build_parser
  :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` .

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_argparse_cli-1.8.3.tar.gz (21.9 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page