sphinx-argparse-neo¶

Beta GitHub PyPI

Modern Sphinx extension for documenting argparse CLIs. The base package registers the argparse directive plus renderer config values; the sphinx_argparse_neo.exemplar layer adds example extraction, lexers, and CLI inline roles.

$ pip install sphinx-argparse-neo

Downstream `conf.py`¶

extensions = [
    "sphinx_argparse_neo",
    "sphinx_argparse_neo.exemplar",
]

argparse_examples_section_title = "Examples"
argparse_reorder_usage_before_examples = True

Live directive demos¶

Base parser rendering¶

Example CLI showing how sphinx-argparse-neo renders parsers.

Usage¶

usage: myapp [-h] [--verbose] [--config PATH]
             {mysubcommand,myothersubcommand} ...

Options¶

--verbose, -v¶

Enable verbose output.

Default: False

--config PATH¶

Path to configuration file.

Default: pyproject.toml

Sub-commands

mysubcommand

Run the primary task.

Execute the primary task with configurable output.

Usage¶

usage: myapp mysubcommand [-h] [--output DIR] [--format {text,json}] [--clean]

Options¶

--output, -o DIR¶

Output directory.

Default: build

--format¶

Output format.

Default: text
Choices: text, json

--clean¶

Remove previous output first.

Default: False

myothersubcommand

Run a secondary task.

Execute a secondary task with network options.

Usage¶

usage: myapp myothersubcommand [-h] [--port PORT] [--host HOST]

Options¶

--port¶

Port number.

Default: 8000
Type: int

--host¶

Host to bind to.

Default: localhost

Subcommand rendering¶

Drill into a single subcommand with :path::

Execute the primary task with configurable output.

Usage¶

usage: myapp mysubcommand [-h] [--output DIR] [--format {text,json}] [--clean]

Options¶

--output, -o DIR¶

Output directory.

Default: build

--format¶

Output format.

Default: text
Choices: text, json

--clean¶

Remove previous output first.

Default: False

Inline roles¶

The exemplar layer also registers live inline roles for CLI prose: myapp, --verbose, json, DIR, and text.

Configuration values¶

Base extension¶

Config Value Index

Name	Type	Default	Rebuild
`argparse_group_title_prefix`	`str`	`''`	`html`
`argparse_show_defaults`	`bool`	`True`	`html`
`argparse_show_choices`	`bool`	`True`	`html`
`argparse_show_types`	`bool`	`True`	`html`

argparse_group_title_prefix¶

Type:: str
Default:: ''

Prefix for argument group titles

Registered by sphinx_argparse_neo.setup().

Rebuild: html.

argparse_show_defaults¶

Type:: bool
Default:: True

Show default values in argument docs

Registered by sphinx_argparse_neo.setup().

Rebuild: html.

argparse_show_choices¶

Type:: bool
Default:: True

Show choice constraints

Registered by sphinx_argparse_neo.setup().

Rebuild: html.

argparse_show_types¶

Type:: bool
Default:: True

Show type information

Registered by sphinx_argparse_neo.setup().

Rebuild: html.

Exemplar layer¶

Config Value Index

Name	Type	Default	Rebuild
`argparse_examples_term_suffix`	`str`	`'examples'`	`html`
`argparse_examples_base_term`	`str`	`'examples'`	`html`
`argparse_examples_section_title`	`str`	`'Examples'`	`html`
`argparse_usage_pattern`	`str`	`'usage:'`	`html`
`argparse_examples_command_prefix`	`str`	`'$ '`	`html`
`argparse_examples_code_language`	`str`	`'console'`	`html`
`argparse_examples_code_classes`	`list`	`['highlight-console']`	`html`
`argparse_usage_code_language`	`str`	`'cli-usage'`	`html`
`argparse_reorder_usage_before_examples`	`bool`	`True`	`html`

argparse_examples_term_suffix¶

Type:: str
Default:: 'examples'

Term suffix for detecting example definition lists