render CLI arguments (sub-commands friendly) defined by argparse module
Project description
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 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) when provided, overwrites the <prog> name. |
| hook | (optional) hook argparse to retrieve the parser if func uses a parser instead of returning it. |
| title | (optional) when provided, overwrites the <prog> - CLI interface title added by default and when empty, will not be included |
| description | (optional) when provided, overwrites the description and when empty, will not be included |
| epilog | (optional) when provided, overwrites the epilog and when empty, will not be included |
| usage_width | (optional) how large should usage examples be - defaults to 100 character |
| usage_first | (optional) show usage before description |
| 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} |
| no_default_values | (optional) suppresses generation of default entries |
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
--magicof therunsub-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
--magicof therunsub-command use:ref:`cli:tox-run---magic`.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_argparse_cli-1.13.0.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f2968bb2a7f0494a455651f52d58260f90b0644724cc6d943b7a2e6e49bba3d0 |
|
| MD5 | 44693c121bf215b085a93175cd8e1157 |
|
| BLAKE2b-256 | 2d99de45689f9b36623a2f90b8bd8926a02e06cc9011cfa6d10211b75edc52da |
Hashes for sphinx_argparse_cli-1.13.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 2cbb8322f02045dc9f447b6eadee9c0c5610ed029199667fd31a8cb700fa2c7c |
|
| MD5 | a1ba179728158cbf76e4a7b7b7cc7b4d |
|
| BLAKE2b-256 | 1eb705326b03df381ac6193b23b24365cd4c6032ef539fb678678e9124b3a63b |
