gem-hunter
Language: Python
Render CLI arguments (sub-commands friendly) defined by the argparse module.
Render CLI arguments (sub-commands friendly) defined by the argparse module.
See the changelog for released changes. The contribution guide explains which pull
requests need a fragment, how to name it, and when to use skip news.
Install the package:
python -m pip install sphinx-argparse-cli
Add the extension to your conf.py:
extensions = ["sphinx_argparse_cli"]
Use the directive in any reStructuredText file:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser
:module: points to the Python module containing the parser, and :func: names a zero-argument function that returns
an ArgumentParser. Build your docs and the full CLI reference appears.
By default the program name comes from the parser. Use :prog: to replace it:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser :prog: my-cli
When a function creates and uses a parser internally without returning it, set the :hook: flag to intercept
argparse.ArgumentParser:
.. sphinx_argparse_cli:: :module: my_project.cli :func: main :hook: :prog: my-cli
Control how group and subcommand headings are rendered with :group_title_prefix: and :group_sub_title_prefix:. Both
accept {prog} and the sub-title also accepts {subcommand}:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser :group_title_prefix: {prog} :group_sub_title_prefix: {prog} {subcommand}
Hide (default: ...) annotations from the output:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser :no_default_values:
Set the character width for usage lines and optionally show usage before the description:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser :usage_width: 80 :usage_first:
Replace auto-detected values, or pass an empty string to suppress them:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser :title: Custom Title :description: Custom description text. :epilog:
The directive registers Sphinx reference labels for every command, group, and flag. Use the :ref: role to link to
them.
With sphinx_argparse_cli_prefix_document = False (default):
:ref:`tox-optional-arguments` :ref:`tox-run` :ref:`tox-run---magic`
With sphinx_argparse_cli_prefix_document = True (anchors prefixed by document name, avoids clashes across documents):
:ref:`cli:tox-optional-arguments` :ref:`cli:tox-run` :ref:`cli:tox-run---magic`
The anchor text is visible after the # in the URL when you click a heading.
Flags and positional arguments are also registered as Sphinx program options, so the :option: role works with the
program (and sub-command) name followed by the argument, or scoped through a .. program:: directive:
:option:`tox --magic` :option:`tox run --magic` .. program:: tox run :option:`--magic` :option:`--magic=value`
:option: targets keep their original case, so they do not need :force_refs_lower:. They ignore
sphinx_argparse_cli_prefix_document; when two documents render the same program, the role links to the first one
Sphinx reads.
Sphinx :ref: only supports lower-case targets. When your program name or flags contain capital letters, set
:force_refs_lower: to convert them. Each upper-case letter becomes its lower-case form prefixed with _ (e.g. A
becomes _a):
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser :force_refs_lower:
For a program named SampleProgram:
:ref:`_sample_program--a` .. flag -a :ref:`_sample_program--_a` .. flag -A
If you do not need Sphinx :ref: cross-references you can leave this off to keep mixed-case anchors in the HTML output,
but enabling it later will change existing anchor URLs.
The directive parses every argument's help string as reStructuredText, so inline markup such as a :ref: role or
**bold** works. The same applies to characters that carry meaning in reStructuredText: a lone * (match *.py), a
trailing _ (name_), backticks, or a trailing :: produce docutils warnings and fail a build run with -W. Escape
them with a backslash (match \*.py) or wrap them in inline literals. Text between matching single quotes, double
quotes, or braces becomes an inline literal for you, so pick 'fast' or "slow" shows 'fast' and "slow" as code.
Any content nested inside the directive is appended after the generated CLI documentation:
.. sphinx_argparse_cli:: :module: my_project.cli :func: build_parser Extra notes or examples rendered after the CLI reference.
| Option | Type | Default | Description |
|---|---|---|---|
:module: |
string | required | Python module path where the parser is defined |
:func: |
string | required | Zero-argument function that returns an ArgumentParser |
:prog: |
string | parser's prog |
Override the displayed program name |
:hook: |
flag | off | Intercept ArgumentParser instead of expecting func to return it |
:title: |
string | <prog> - CLI interface |
Custom title; empty string suppresses it |
:description: |
string | parser's description | Custom description; empty string suppresses it |
:epilog: |
string | parser's epilog | Custom epilog; empty string suppresses it |
:usage_width: |
int | 100 |
Character width for usage lines |
:usage_first: |
flag | off | Show usage before the description |
:group_title_prefix: |
string | {prog} |
Heading prefix for groups; {prog} is replaced with the program name |
:group_sub_title_prefix: |
string | {prog} {subcommand} |
Heading prefix for subcommand groups; supports {prog} and {subcommand} |
:no_default_values: |
flag | off | Suppress (default: ...) annotations |
:force_refs_lower: |
flag | off | Lower-case reference anchors with _ prefix for capitals (for :ref: compat) |
| Name | Type | Default | Description |
|---|---|---|---|
sphinx_argparse_cli_prefix_document |
bool | False |
Prefix reference anchors with the document name to avoid clashes |