API Reference¶

Cross-reference roles¶

Every .. argparse:: block populates a dedicated argparse domain alongside the existing std:cmdoption entries. Use these roles to link to programs, options, subcommands, and positional arguments declared anywhere in the project:

Role	Resolves to	Example
`:argparse:program:`	A top-level program	:argparse:program:`myapp`
`:argparse:option:`	An optional flag, scoped by program	:argparse:option:`myapp --verbose` or :argparse:option:`myapp sync --force`
`:argparse:subcommand:`	A subcommand under a parent program	:argparse:subcommand:`myapp sync`
`:argparse:positional:`	A positional argument, scoped by program	:argparse:positional:`myapp FILE`

Whitespace-joined targets (myapp sync --force) are split on the final space to match the stored (program, name) tuple. Bare forms (--verbose) also resolve when only one registration matches, though the fully-qualified form is preferred for multi-program sites.

Auto-generated indices¶

Two domain indices are built into every project that loads the extension:

argparse-programsindex — alphabetised list of every registered program; link via :ref:`argparse-programsindex`.
argparse-optionsindex — options grouped by program, alphabetised within each group; link via :ref:`argparse-optionsindex`.

Intersphinx compatibility¶

The classic :option: / std:cmdoption emission is preserved — both roles resolve and both appear in objects.inv. Downstream consumers linking via intersphinx continue to work; new authoring inside projects using this extension can prefer the :argparse:* namespace for program-scoped clarity.

Configuration values¶

Base extension¶

argparse_group_title_prefix ¶ config html config html argparse_group_title_prefix ¶

Prefix for argument group titles

Type:: str
Default:: ''
Registered by:: sphinx_autodoc_argparse.setup()

argparse_show_defaults ¶ config html config html argparse_show_defaults ¶

Show default values in argument docs

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.setup()

argparse_show_choices ¶ config html config html argparse_show_choices ¶

Show choice constraints

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.setup()

argparse_show_types ¶ config html config html argparse_show_types ¶

Show type information

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.setup()

Exemplar layer¶

argparse_examples_term_suffix ¶ config html config html argparse_examples_term_suffix ¶

Term suffix for detecting example definition lists

Type:: str
Default:: 'examples'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_base_term ¶ config html config html argparse_examples_base_term ¶

Base term for matching example sections

Type:: str
Default:: 'examples'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_section_title ¶ config html config html argparse_examples_section_title ¶

Section title for extracted examples

Type:: str
Default:: 'Examples'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_usage_pattern ¶ config html config html argparse_usage_pattern ¶

Pattern to detect usage blocks in epilog text

Type:: str
Default:: 'usage:'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_command_prefix ¶ config html config html argparse_examples_command_prefix ¶

Prefix for example commands in code blocks

Type:: str
Default:: '$ '
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_code_language ¶ config html config html argparse_examples_code_language ¶

Language for example code blocks

Type:: str
Default:: 'console'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_examples_code_classes ¶ config html config html argparse_examples_code_classes ¶

CSS classes for example code blocks

Type:: list
Default:: ['highlight-console']
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_usage_code_language ¶ config html config html argparse_usage_code_language ¶

Language for usage code blocks

Type:: str
Default:: 'cli-usage'
Registered by:: sphinx_autodoc_argparse.exemplar.setup()

argparse_reorder_usage_before_examples ¶ config html config html argparse_reorder_usage_before_examples ¶

Move usage sections before examples sections

Type:: bool
Default:: True
Registered by:: sphinx_autodoc_argparse.exemplar.setup()