click_extra.sphinx package

Helpers and utilities for Sphinx.

Note

The MkDocs counterpart lives in click_extra.mkdocs, which achieves the same ANSI color rendering by patching pymdownx.highlight’s formatter classes.

click_extra.sphinx.MYST_NATIVE_ALERTS_VERSION = <Version('5.1.0')>

First myst-parser release that ships the native "alert" syntax extension.

Below this version, click_extra.sphinx.alerts patches GitHub alert syntax into MyST admonitions via a source-read / include-read hook. At or above this version, the converter is skipped at setup() time and projects should add "alert" to myst_enable_extensions instead.

click_extra.sphinx.EXEC_DIRECTIVES_OPT_IN = 'click_extra_enable_exec_directives'

Name of the conf.py config flag that gates every code-execution directive.

Default is False. A project that adds click_extra.sphinx to its extensions list gets the ANSI Pygments formatter unconditionally, plus the GitHub-alerts converter when myst-parser is below MYST_NATIVE_ALERTS_VERSION (see alerts for the deprecation rationale), but does not gain access to either the click:* or the python:* directive families until the maintainer opts in explicitly. Both families exec user-supplied Python at build time with full Sphinx-process privileges; gating them behind a single explicit flag keeps a transitive import or a doc-only pull request from silently expanding the build’s attack surface.

click_extra.sphinx.RUN_CAPTURE_CONFIG = 'click_extra_run_capture'

Name of the conf.py value selecting the stream-capture mode for the CLIs that click:run and click:tree execute.

Maps to the capture parameter of Click’s CliRunner, "sys" or "fd" (added in Click 8.4). Defaults to "fd" so a command writing through sys.stdout.fileno() is captured at the file-descriptor level and renders, instead of aborting the build with io.UnsupportedOperation. Ignored on Click releases older than 8.4, which lack the parameter.

click_extra.sphinx.setup(app)

Register extensions to Sphinx.

Always-on features (no execution surface):

• The ANSI-capable HTML formatter for Pygments (replaces sphinx.highlighting.PygmentsBridge with one that renders ANSI colors in code blocks).

• GitHub-flavored alert syntax (> [!NOTE], etc.) in included and regular source files, converted to MyST/reST admonitions. Registered only when the installed myst-parser is below MYST_NATIVE_ALERTS_VERSION (5.1.0). On newer versions, the converter is skipped and a one-shot info message points users at myst-parser’s native "alert" extension. See click_extra.sphinx.alerts for the deprecation plan.

• The matrix directive, which renders a package’s compatibility grid ({matrix} python or {matrix} <distribution>) from its git tag history. It runs a canned generator rather than user-supplied Python, so it carries no execution surface and needs no opt-in. See click_extra.sphinx.matrix.

Opt-in features (gated behind click_extra_enable_exec_directives):

• click:source / click:run to define and execute Click CLIs at build time.

• python:source / python:run to execute arbitrary Python at build time and render its source or captured stdout.

• python:render / python:render-myst / python:render-rst to execute arbitrary Python and parse the captured stdout as live document content.

All directives in the opt-in group execute user-supplied Python with the same privileges as the Sphinx process. They are therefore disabled by default. Set click_extra_enable_exec_directives = True in conf.py to register them.

Caution

This function forces the Sphinx app to use sphinx.highlighting.PygmentsBridge instead of the default HTML formatter to add support for ANSI colors in code blocks.

Return type:

ExtensionMetadata

Submodules

click_extra.sphinx.alerts module

Utilities to convert GitHub alerts into MyST admonitions for Sphinx.

Deprecated since version 7.16.0: myst-parser 5.1+ ships a native "alert" syntax extension that renders GitHub alerts as Sphinx admonitions, covering the same ground as this regex-based converter. click_extra.sphinx.setup() only wires the converter into Sphinx when the installed myst-parser is below 5.1.0 (see click_extra.sphinx.MYST_NATIVE_ALERTS_VERSION); on newer releases the hook is skipped at setup time and a log message points projects at myst-parser’s native extension, which they enable by adding "alert" to myst_enable_extensions. I plan to remove the module entirely once the myst-parser floor moves to >=5.1.

See also

• GitHub documentation for `alerts syntax

<https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts>`_. - Announcement for alert support starting 2023-12-14. - MyST-parser “alert” syntax extension added in version 5.1.0.

click_extra.sphinx.alerts.GITHUB_ALERT_PATTERN = re.compile('^\\s*\\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\\]\\s*$')

Regex pattern to match GitHub alert type declaration (without leading >).

click_extra.sphinx.alerts.QUOTE_PREFIX_PATTERN = re.compile('^(\\s*)((?:>\\s*)+)(.*)$')

Regex pattern to extract indent, quote markers, and content.

click_extra.sphinx.alerts.CODE_FENCE_PATTERN = re.compile('^(\\s*)(`{3,}|~{3,})(.*)$')

Regex pattern to match code fence opening/closing lines.

click_extra.sphinx.alerts.INDENTED_CODE_BLOCK_PATTERN = re.compile('^( {4}|\\t)')

Regex pattern to match indented code block lines (4 spaces or 1 tab).

class click_extra.sphinx.alerts.Alert(alert_type, indent, depth, has_nested=False, opening_line_index=0)

Bases: object

Represents a GitHub alert being processed.

alert_type: str

indent: str

depth: int

has_nested: bool = False

opening_line_index: int = 0

class click_extra.sphinx.alerts.FenceState(char, length, indent, is_code_block)

Bases: object

Tracks code fence state.

char: str

length: int

indent: str

is_code_block: bool

class click_extra.sphinx.alerts.ParserState(result=<factory>, alert_stack=<factory>, fence_stack=<factory>, prev_line_blank=True, modified=False, just_opened_fence_directive=False)

Bases: object

Mutable state for the alert parser.

result: list[str]

alert_stack: list[Alert]

fence_stack: list[FenceState]

prev_line_blank: bool = True

modified: bool = False

just_opened_fence_directive: bool = False

in_code_block()

Check if currently inside a code block.

Return type:

bool

current_depth()

Get current alert nesting depth.

Return type:

int

click_extra.sphinx.alerts.check_colon_fence(app: Sphinx) → None

Check that colon_fence support is enabled for MyST.

Raises:

ConfigError – If colon_fence is not in myst_enable_extensions.

Return type:

None

click_extra.sphinx.alerts.count_quote_depth(line)

Parse a line to extract indent, quote depth, and content.

Return type:

tuple[str, int, str]

Returns:

tuple of (indent, depth, content) where depth is the number of > markers.

click_extra.sphinx.alerts.process_fence(state, indent, chars, after)

Process a fence line, updating fence stack.

Return type:

None

click_extra.sphinx.alerts.close_alerts_to_depth(state, target_depth)

Close all alerts deeper than target_depth.

When the alert has no body content (just the directive line, like a bare > [!TIP]), inject a MyST comment placeholder before the closing fence. Sphinx silently drops admonitions with an empty body, but myst-parser 5.1+’s native "alert" extension renders a title-only admonition for that input. The MyST comment is consumed at parse time, so the rendered HTML matches the upstream output: <div class="admonition tip"><p class="admonition-title">Tip</p></div>.

Return type:

None

click_extra.sphinx.alerts.mark_parent_nested(state)

Mark the parent alert as having a nested alert and update its opening.

Return type:

None

click_extra.sphinx.alerts.open_alert(state, alert_type, indent, depth)

Open a new alert at the given depth.

Return type:

None

click_extra.sphinx.alerts.process_quoted_line(state, line)

Process a line that starts with quote markers.

Returns True if the line was handled as part of an alert.

Return type:

bool

click_extra.sphinx.alerts.replace_github_alerts(text)

Transform GitHub alerts into MyST admonitions.

Identify GitHub alerts in the provided text and transform them into colon-fenced ::: MyST admonitions.

Returns None if no transformation was applied, else returns the transformed text.

Return type:

str | None

click_extra.sphinx.alerts.convert_github_alerts(app, *args)

Convert GitHub alerts into MyST admonitions in content blocks.

Return type:

None

click_extra.sphinx.click module

Sphinx rendering of CLI based on Click Extra.

See also

These directives are based on Pallets’ Sphinx Themes, released under a BSD-3-Clause license.

Compared to the latter, it:

• Add support for MyST syntax.

• Adds rendering of ANSI codes in CLI results.

• Has better error handling and reporting which helps you pinpoint the failing code in your documentation.

• Removes the println function which was used to explicitly print a blank line. This is no longer needed as it is now handled natively.

click_extra.sphinx.click.RST_INDENT = '   '

The indentation used for rST code blocks lines.

class click_extra.sphinx.click.TerminatedEchoingStdin(input, output)

Bases: EchoingStdin

Like click.testing.EchoingStdin but adds a visible ^D in place of the EOT character ().

ClickRunner.invoke() adds  when terminate_input=True.

click_extra.sphinx.click.patch_subprocess()

Patch subprocess to work better with ClickRunner.invoke().

subprocess.call output is redirected to click.echo so it shows up in the example output.

Caution

The replacement is installed on the subprocess module itself (not thread-local), so for the duration of the with block any other code in the same process that calls subprocess.call sees the patched version. With parallel_read_safe = True declared on ClickDomain, a parallel reader running concurrently on a different document gets the patched subprocess.call too. The redirection is benign (output goes to click.echo) but the race is real, and the parallel-safe claim is weaker than it looks for documents that themselves shell out via subprocess.call.

class click_extra.sphinx.click.ClickRunner(capture=None)

Bases: CliRunner

A sub-class of click.testing.CliRunner for Sphinx directive execution.

Produces unfiltered ANSI codes so that the Directive sub-classes below can render colors in the HTML output. Because Click Extra executes the documented command here, invoke() forces color across both color systems a CLI might use: color=True covers Click’s (should_strip_ansi), and forced_color() sets FORCE_COLOR for Rich’s (which rich-click uses and color=True never reaches). The MkDocs plugin shares the latter lever but cannot pass color=True, since it patches a renderer it never executes.

On Click 8.4+ the runner defaults to capture="fd" on Unix (overridable through the click_extra_run_capture conf.py value) so a documented command that writes through sys.stdout.fileno() is captured and rendered, instead of aborting the build with io.UnsupportedOperation. On Windows, where fd-backed streams are not supported, the default falls back to capture="sys".

isolation(*args, **kwargs)

A context manager that sets up the isolation for invoking of a command line tool. This sets up <stdin> with the given input data and os.environ with the overrides from the given dictionary. This also rebinds some internals in Click to be mocked (like the prompt functionality).

This is automatically done in the invoke() method.

Parameters:

• input – the input stream to put into sys.stdin.

• env – the environment overrides as dictionary.

• color – whether the output should contain color codes. The application can still override this explicitly.

Added in version 8.2: An additional output stream is returned, which is a mix of <stdout> and <stderr> streams.

Changed in version 8.2: Always returns the <stderr> stream.

Changed in version 8.0: <stderr> is opened with errors="backslashreplace" instead of the default "strict".

Changed in version 4.0: Added the color parameter.

invoke(cli, args=None, prog_name=None, input=None, terminate_input=False, env=None, _output_lines=None, **extra)

Like CliRunner.invoke but displays what the user would enter in the terminal for env vars, command arguments, and prompts.

Parameters:

• terminate_input – Whether to display ^D after a list of input.

• _output_lines – A list used internally to collect lines to be displayed.

Return type:

Result

execute_source(directive)

Execute the given code, adding it to the runner’s namespace.

Return type:

None

run_cli(directive)

Execute the given source_code.

Returns a simulation of terminal execution, including a mix of input, output, prompts and tracebacks.

The execution context is augmented, so you can refer directly to these functions in the provided source_code:

• invoke(): which is the same as ClickRunner.invoke()

• isolated_filesystem(): A context manager that changes to a temporary directory while executing the block.

If any local variable in the provided source_code conflicts with these functions, a RuntimeError is raised to help you pinpoint the issue.

Return type:

list[str]

class click_extra.sphinx.click.ClickDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SphinxDirective

has_content = True

May the directive have content?

required_arguments = 0

Number of required directive arguments.

optional_arguments = 1

The optional argument overrides the default Pygments language to use.

final_argument_whitespace = False

May the final argument contain whitespace?

option_spec: ClassVar[OptionSpec] = {'caption': <function unchanged_required>, 'class': <function class_option>, 'dedent': <function optional_int>, 'emphasize-lines': <function unchanged_required>, 'emphasize-result-lines': <function unchanged_required>, 'force': <function flag>, 'hide-results': <function flag>, 'hide-source': <function flag>, 'language': <function unchanged_required>, 'lineno-start': <class 'int'>, 'linenos': <function flag>, 'name': <function unchanged>, 'show-results': <function flag>, 'show-source': <function flag>}

Options supported by this directive.

Support the same options as sphinx.directives.code.CodeBlock, and some specific to Click directives.

The standard emphasize-lines option applies to the source block only. Use emphasize-result-lines to highlight specific lines in the captured output block, with the same syntax (like :emphasize-result-lines: 1,3-5).

default_language: str

Default highlighting language to use to render the code block.

All Pygments’ languages short names are recognized.

show_source_by_default: bool = True

Whether to render the source code of the example in the code block.

show_results_by_default: bool = True

Whether to render the results of the example in the code block.

runner_method: str

The name of the method to call on the ClickRunner instance.

runner_attr: ClassVar[str] = 'click_runner'

Name of the attribute holding the runner on the doctree.

Subclasses (like PythonDirective) override this so the Click and Python runners don’t collide on the same document.

runner_factory

Class to instantiate for the per-document runner.

Defaults to ClickRunner in ClickDirective (set after the class definition to break the forward reference).

alias of ClickRunner

property runner

Get or create the per-document runner.

Creates one runner per document, keyed by runner_attr.

property language: str

Short name of the Pygments lexer used to highlight the code block.

Returns, in order of precedence, the language specified in the :language: directive options, the first argument of the directive (if any), or the default set in the directive class.

code_block_options(target='source')

Render the options supported by Sphinx’ native code-block directive.

target selects which block these options will be attached to: "source" for the directive’s input source code, "results" for the captured output. emphasize-lines routes to the source block; emphasize-result-lines is rewritten as emphasize-lines on the results block, so authors can highlight different lines in each.

Return type:

list[str]

property show_source: bool

Whether to show the source code of the example in the code block.

The last occurrence of either show-source or hide-source options wins. If neither is set, the default is taken from show_source_by_default.

property show_results: bool

Whether to show the results of running the example in the code block.

The last occurrence of either show-results or hide-results options wins. If neither is set, the default is taken from show_results_by_default.

property is_myst_syntax: bool

Check if the current directive is written with MyST syntax.

render_code_block(lines, language, target='source')

Render the code block with the source code or results.

target is forwarded to code_block_options() so the emphasize-lines / emphasize-result-lines split routes the right highlighting to each block.

Return type:

list[str]

run()

Return type:

list[Node]

class click_extra.sphinx.click.SourceDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: ClickDirective

Directive to declare a Click CLI source code.

This directive is used to declare a Click CLI example in the documentation. It renders the source code of the example in a Python code block.

default_language: str = 'python'

Default highlighting language to use to render the code block.

All Pygments’ languages short names are recognized.

show_source_by_default: bool = True

Whether to render the source code of the example in the code block.

show_results_by_default: bool = False

Whether to render the results of the example in the code block.

runner_method: str = 'execute_source'

The name of the method to call on the ClickRunner instance.

class click_extra.sphinx.click.RunDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: ClickDirective

Directive to run a Click CLI example.

This directive is used to run a Click CLI example in the documentation. It renders the results of running the example in a shell session code block supporting ANSI colors.

default_language: str = 'ansi-shell-session'

Default highlighting language to use to render the code block.

All Pygments’ languages short names are recognized.

show_source_by_default: bool = False

Whether to render the source code of the example in the code block.

show_results_by_default: bool = True

Whether to render the results of the example in the code block.

runner_method: str = 'run_cli'

The name of the method to call on the ClickRunner instance.

class click_extra.sphinx.click.TreeDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: ClickDirective

Render a complete CLI reference for a Click command and all its subcommands.

Walks the Click command tree at build time and emits, in MyST syntax:

• A GFM summary table linking each command to its section anchor.

• A heading + click:run --help block for the root command.

• One heading + click:run --help block per subcommand, nested by depth.

Designed to replace per-project hand-rolled generators (like repomatic’s docs_update.py::cli_reference()) with a single declarative directive that walks the live command tree on every build.

The required argument is a Python expression evaluated in the per-document runner namespace; it must yield a click.Command. The optional directive body is Python preamble exec’d in the same namespace before evaluation, so authors may either import the CLI in a prior click:source :hide-source: block or inline the import here.

Note

Currently MyST-only. Use the directive in a .md document with myst_parser enabled.

has_content = True

May the directive have content?

required_arguments = 1

Number of required directive arguments.

optional_arguments = 0

The optional argument overrides the default Pygments language to use.

final_argument_whitespace = False

May the final argument contain whitespace?

option_spec: ClassVar[OptionSpec] = {'anchor-prefix': <function unchanged>, 'heading-offset': <function nonnegative_int>, 'label-prefix': <function unchanged>, 'max-depth': <function positive_int>, 'no-root': <function flag>, 'no-table': <function flag>, 'root-label': <function unchanged>}

Recognized directive options.

max-depth caps the recursion into nested click.Group commands (default: 10). heading-offset shifts all generated headings down by N levels. When unset, the directive reads state.memo.section_level and uses the surrounding section depth so the root nests one level below the enclosing section: inside the document’s h1 title this yields 1 (root at h2); inside an h3 section it yields 3 (root at h4). Override only when the auto-detected depth is wrong for the page layout. anchor-prefix and label-prefix override the slug and display prefix used for anchors and labels; both default to the CLI’s click.Command.name. root-label sets the heading text for the root help block (default: "Help screen"). no-table skips the summary table; no-root skips the root --help block.

run()

Return type:

list[Node]

class click_extra.sphinx.click.ConfigDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: ClickDirective

Render the configuration reference of a CLI’s config_schema.

Introspects a configuration schema dataclass at build time and expands, in MyST syntax:

• A GFM summary table linking each option to its section anchor, with its one-line summary and default value.

• One heading per option, with its docstring, type, default, and a TOML example pinned to the default value.

Option metadata comes from schema_field_infos(): dotted kebab-case keys, type annotations, defaults from a pristine schema instance, and attribute docstrings (which are parsed as the host document’s markup). Designed to replace per-project hand-rolled generators (like repomatic’s docs_update.py::config_deflist()) with a single declarative directive that documents the live schema on every build.

The required argument is a Python expression evaluated in the per-document runner namespace; it must yield either a click.Command whose config_schema is set (the schema is pulled off its ConfigOption), or a schema dataclass directly. The optional directive body is Python preamble exec’d in the same namespace before evaluation, so authors may either import the CLI in a prior click:source :hide-source: block or inline the import here.

Caution

Attribute docstrings are recovered from the schema’s source file, so a schema defined inside an exec’d click:source block documents its options without descriptions. Import the schema from a real module instead (see field_docstrings()).

Note

Currently MyST-only. Use the directive in a .md document with myst_parser enabled.

has_content = True

May the directive have content?

required_arguments = 1

Number of required directive arguments.

optional_arguments = 0

The optional argument overrides the default Pygments language to use.

final_argument_whitespace = False

May the final argument contain whitespace?

option_spec: ClassVar[OptionSpec] = {'heading-offset': <function nonnegative_int>, 'no-examples': <function flag>, 'no-table': <function flag>, 'section': <function unchanged>}

Recognized directive options.

heading-offset shifts all generated headings down by N levels; when unset, the surrounding section depth is used (same behavior as click:tree). section overrides the TOML table header shown in the per-option examples: it defaults to tool.{cli-name} when the argument is a CLI (matching how click-extra and its downstream CLIs read their section from pyproject.toml), and to no header at all for a bare schema; an explicitly empty :section: suppresses the header. no-table skips the summary table; no-examples skips the TOML example blocks.

run()

Return type:

list[Node]

class click_extra.sphinx.click.ClickDomain(env)

Bases: StatelessDomain

Setup new directives under the same click namespace:

• click:source which renders a Click CLI source code

• click:run which renders the results of running a Click CLI

• click:tree which walks a Click command tree and renders the full --help reference for every subcommand, with a summary table on top

• click:config which documents a CLI’s config_schema: a summary table plus one section per option, with types, defaults, and TOML examples

name: ClassVar[str] = 'click'

domain name: should be short, but unique

label: ClassVar[str] = 'Click'

domain label: longer, more descriptive (used in messages)

directives: ClassVar[dict] = {'config': <class 'click_extra.sphinx.click.ConfigDirective'>, 'run': <class 'click_extra.sphinx.click.RunDirective'>, 'source': <class 'click_extra.sphinx.click.SourceDirective'>, 'tree': <class 'click_extra.sphinx.click.TreeDirective'>}

directive name -> directive class

click_extra.sphinx.click.cleanup_runner(app, doctree)

Drop the ClickRunner from the doctree once the document is read.

Return type:

None

click_extra.sphinx.manpages module

Sphinx integration to render roff man pages alongside the HTML build.

A project that adds click_extra.sphinx to its extensions list and declares one or more entries in click_extra_manpages gets its Click command tree(s) emitted as .1 files into <outdir>/<output_dir>/ on every HTML build, with no project-local helper script. Pages mirror what click_extra.man_page.write_manpages() produces from a CLI invocation, so the docs site, the release pipeline, and downstream packagers all share one generator.

When mandoc or groff is available on PATH, each .1 file is also rendered to a browser-viewable .html sibling. Browsers download raw .1 files rather than display them, so the HTML pass is what makes Sphinx’s :manpage: role useful when manpages_url points at this hook’s output.

The hook only fires for HTML-class builders (html, dirhtml, singlehtml). Non-HTML builders (linkcheck, man, epub, coverage, etc.) skip it: they typically have different output semantics, and writing roff into a linkcheck output/ directory serves no purpose.

Configuration shape:

click_extra_manpages = [
    {
        "script": "meta_package_manager.cli:mpm",  # required
        "prog_name": "mpm",  # optional, see below
        "output_dir": "man",  # optional, defaults to "man"
        "render_html": True,  # optional, see below
    },
]

• script is resolved by click_extra.cli_wrapper.resolve_target_command() exactly as it would be from the click-extra man CLI: a console_scripts entry-point name, a module:function path, a .py file, or a plain module name.

• prog_name is the basename used for both the man-page .TH header and the generated filenames. When omitted, it falls back to the resolved Click command’s own name attribute (mpm for the meta_package_manager.cli:mpm target), matching the default the click-extra man --output-dir CLI uses.

• output_dir is a relative path under app.outdir. It is created on demand and reused across builds.

• render_html toggles the HTML sibling pass. Defaults to True. When no renderer is on PATH, the build still produces the .1 files and logs a single info-level notice; set render_html to False to suppress that notice.

An empty (or absent) click_extra_manpages list disables the feature, which is the default for every project pulling in the extension.

Cross-referencing the generated pages from prose

To make :manpage:`myprog(1)` resolve to the HTML sibling this hook emits, set Sphinx’s manpages_url to the same output_dir:

manpages_url = "man/{page}.{section}.html"

Sphinx’s role provides {page}, {section} and {path} placeholders; the file layout produced here is {page}.{section} plus the optional .html extension, so the template above matches every file regardless of how deep the subcommand tree goes.

click_extra.sphinx.manpages.MANPAGES_CONFIG_KEY = 'click_extra_manpages'

Name of the conf.py config flag holding the man-page emit list.

click_extra.sphinx.manpages.DEFAULT_OUTPUT_DIR = 'man'

Subdirectory under app.outdir where .1 files land when the caller omits the output_dir entry. Picked to match the URL fragment projects typically publish their man pages under (like https://example.com/<project>/man/<cli>.1).

click_extra.sphinx.manpages.HTML_BUILDER_NAMES = frozenset({'dirhtml', 'html', 'singlehtml'})

Builder names that get the man-page emit hook.

Restricted to HTML-family builders because they are the ones whose output directory becomes the published docs site. Other builders (linkcheck, man, epub, coverage) have different output semantics, and writing roff into their build trees would either be redundant or confusing.

click_extra.sphinx.manpages.HTML_RENDERERS: tuple[tuple[str, tuple[str, ...]], ...] = (('mandoc', ('-Thtml',)), ('groff', ('-Thtml', '-mandoc')))

External roff → HTML renderers, tried in order.

mandoc is preferred: its HTML output ships semantic id anchors on every section and option (#NAME, #SYNOPSIS, #config…), which makes deep-linking from prose work. groff -Thtml -mandoc is the GNU fallback. If neither is on PATH, the HTML pass is skipped and only the .1 files are emitted.

click_extra.sphinx.manpages.MANPAGE_LIST_DIRECTIVE = 'click-extra-manpages'

Name of the directive that renders an auto-generated index of every man page declared in MANPAGES_CONFIG_KEY. The hyphenated form mirrors the click_extra_manpages config key it surfaces.

class click_extra.sphinx.manpages.ManpageListDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SphinxDirective

Render a bullet list with one link per emitted man page.

The directive walks every entry in MANPAGES_CONFIG_KEY and, for each, calls iter_command_contexts() to discover the (sub)command tree. Each list item links to the corresponding .1.html file written by the emit hook.

Link targets are computed relative to the directive’s enclosing document so the list works whether it appears at the docs root or in a nested page. The directive takes no arguments and no content: it surfaces whatever the config declares at the time the doc is built.

has_content = False

May the directive have content?

required_arguments = 0

Number of required directive arguments.

optional_arguments = 0

Number of optional arguments after the required arguments.

run()

Return type:

list[Node]

click_extra.sphinx.manpages.setup(app)

Register the man-page emit hook and the index directive on app.

Called from click_extra.sphinx.setup() so projects only need to list "click_extra.sphinx" in their extensions. The hook is a no-op when click_extra_manpages is unset or empty, and the directive renders nothing in that case.

Return type:

None

click_extra.sphinx.matrix module

Release compatibility matrices derived from a project’s git history.

Walk every vX.Y.Z tag in a project’s git repository, extract each release’s declared support for some axis, group consecutive tags that agree, and render a GitHub-flavored markdown matrix suitable for a project’s install.md.

Two axes are supported:

• Python ({matrix} python): per-tag support comes from the Programming Language :: Python :: X.Y classifier list in pyproject.toml (the explicit tested grid), falling back in priority order to PEP 621 requires-python, Poetry [tool.poetry.dependencies].python, and setup.py’s python_requires. A floor-only declaration is capped at the latest Python released while the range was current, so the ✅ set does not over-claim support for Pythons that did not yet exist.

• A dependency ({matrix} <distribution>, like {matrix} click): the per-tag constraint is that distribution’s requirement specifier; columns are auto-derived from the specifier boundaries plus the uv.lock resolved version, and each ✅ / ❌ cell is computed with packaging.

The rendered tables back the always-on matrix Sphinx directive (see MatrixDirective), so a project’s install.md can embed a live matrix kept current by the click-extra refresh-directives command instead of a static table maintained by hand. The generation functions shell out to git; they carry no runtime CLI relevance and are kept out of the click_extra public API.

click_extra.sphinx.matrix.PYTHON_RELEASE_DATES: dict[str, str] = {'2.7': '2010-07-03', '3.0': '2008-12-03', '3.1': '2009-06-27', '3.10': '2021-10-04', '3.11': '2022-10-24', '3.12': '2023-10-02', '3.13': '2024-10-07', '3.14': '2025-10-07', '3.2': '2011-02-20', '3.3': '2012-09-29', '3.4': '2014-03-16', '3.5': '2015-09-13', '3.6': '2016-12-23', '3.7': '2018-06-27', '3.8': '2019-10-14', '3.9': '2020-10-05'}

ISO release date of each X.Y Python final release.

Used to cap ✅ cells when a release range’s Python support is derived from a requires-python-style floor rather than an explicit classifier list: a floor without upper bound would otherwise over-claim support for Pythons that did not yet exist while the range was current. Update this table each October when a new final release ships.

click_extra.sphinx.matrix.DEFAULT_TAG_PATTERN: str = '^v\\d+\\.\\d+\\.\\d+$'

Default regex for release tags (vMAJOR.MINOR.PATCH).

click_extra.sphinx.matrix.DEFAULT_TAGS_SORT: str = 'version:refname'

Default git tag --sort argument.

class click_extra.sphinx.matrix.PythonMatrixGroup(first_tag: str, last_tag: str, first_date: str, python_versions: tuple[str, ...])

Bases: NamedTuple

A contiguous run of release tags sharing the same Python support set.

Create new instance of PythonMatrixGroup(first_tag, last_tag, first_date, python_versions)

first_tag: str

First tag in the group (in git tag --sort=version:refname order).

last_tag: str

Last tag in the group.

first_date: str

ISO YYYY-MM-DD date of the first tag’s commit.

python_versions: tuple[str, ...]

The X.Y Python versions this range supports, sorted ascending.

click_extra.sphinx.matrix.python_versions_released_by(cutoff_date, release_dates=None)

Return Python X.Y versions released on or before cutoff_date.

Parameters:

• cutoff_date (str) – ISO YYYY-MM-DD date.

• release_dates (dict[str, str] | None) – mapping of X.Y → ISO release date. Defaults to PYTHON_RELEASE_DATES.

Return type:

list[str]

Returns:

sorted list of X.Y strings.

click_extra.sphinx.matrix.parse_python_spec(spec)

Parse a Python version spec into (floor, ceiling, excluded).

Supports:

• PEP 440: >=3.10, >=3.10,<3.14, >=2.7, !=3.0.*, !=3.1.*.

• Poetry caret: ^3.7 expands to >=3.7, <4.0.

• Poetry tilde: ~3.7 expands to >=3.7, <3.8.

• setup.py’s python_requires (uses the same PEP 440 syntax as requires-python).

Return type:

tuple[str, str, set[str]]

Returns:

(floor, ceiling, excluded) where each of floor and ceiling is a bare "X.Y" string (empty if unspecified) and excluded is the set of bare "X.Y" values one per !=X.Y.* clause. The ceiling is exclusive: <3.14 means 3.14 itself is not supported. Returns ("", "", set()) when no floor is found.

click_extra.sphinx.matrix.python_matrix_groups(project_root, *, tag_pattern='^v\\\\d+\\\\.\\\\d+\\\\.\\\\d+$', tags_sort='version:refname', version_floor='', release_dates=None)

Walk every release tag in project_root and group consecutive releases that declare the same effective set of Python versions.

Parameters:

• project_root (Path) – git working tree to walk.

• tag_pattern (str) – regex matching release tags. Defaults to DEFAULT_TAG_PATTERN (vMAJOR.MINOR.PATCH).

• tags_sort (str) – value passed to git tag --sort. Defaults to DEFAULT_TAGS_SORT (version:refname).

• version_floor (str) – drop every release tag below this bare version ("4.9.0", "4.9"). Empty (the default) keeps all tags. Applied before grouping so the oldest surviving group starts at the floor.

• release_dates (dict[str, str] | None) – Python-version release-date table used for the cap. Defaults to PYTHON_RELEASE_DATES.

Return type:

list[PythonMatrixGroup]

Returns:

List of PythonMatrixGroup, in chronological order. Tags with no Python declaration in any recognized form are skipped.

click_extra.sphinx.matrix.python_matrix_table(project_root, label, *, tag_pattern='^v\\\\d+\\\\.\\\\d+\\\\.\\\\d+$', tags_sort='version:refname', python_floor='', version_floor='', release_dates=None)

Render the Python compatibility matrix as a GitHub-flavored markdown table.

Newest releases sit on top so the supported-version streak progresses from the upper-left toward the lower-right corner over time.

Parameters:

• project_root (Path) – git working tree to walk.

• label (str) – the header column name (usually the package name, like "click-extra" or "repomatic"). Rendered in backticks.

• tag_pattern (str) – passed to python_matrix_groups().

• tags_sort (str) – passed to python_matrix_groups().

• python_floor (str) – drop every Python X.Y column below this bare version ("3.9"). Empty (the default) keeps all columns. Trims columns only; combine with version_floor to also drop the old release rows that supported nothing above the floor.

• version_floor (str) – passed to python_matrix_groups() to drop release rows below a bare package version.

• release_dates (dict[str, str] | None) – passed to python_matrix_groups().

Return type:

str

Returns:

rendered markdown table, or the empty string when no group was collected.

class click_extra.sphinx.matrix.DependencyMatrixGroup(first_tag: str, last_tag: str, first_date: str, spec: str)

Bases: NamedTuple

A contiguous run of release tags declaring the same dependency spec.

Create new instance of DependencyMatrixGroup(first_tag, last_tag, first_date, spec)

first_tag: str

First tag in the group (in git tag --sort=version:refname order).

last_tag: str

Last tag in the group.

first_date: str

ISO YYYY-MM-DD date of the first tag’s commit.

spec: str

The raw requirement specifier declared for the dependency at this range.

click_extra.sphinx.matrix.dependency_matrix_groups(project_root, dep_name, *, tag_pattern='^v\\\\d+\\\\.\\\\d+\\\\.\\\\d+$', tags_sort='version:refname', version_floor='')

Group consecutive release tags declaring the same dep_name spec.

Parameters:

dep_name (str) – the distribution whose requirement specifier is tracked (like "click").

Return type:

list[DependencyMatrixGroup]

Returns:

DependencyMatrixGroup list in chronological order; tags with no declared requirement for dep_name are skipped.

click_extra.sphinx.matrix.dependency_matrix_table(project_root, label, dep_name, *, show_spec=False, tag_pattern='^v\\\\d+\\\\.\\\\d+\\\\.\\\\d+$', tags_sort='version:refname', version_floor='')

Render the dep_name compatibility matrix as a markdown table.

Columns are auto-derived from the requirement specifiers across history (see _dependency_columns()) plus the uv.lock resolved version; each ✅ / ❌ cell is computed with packaging. Consecutive ranges whose cells coincide are re-merged into one row.

Parameters:

• label (str) – header column name (the documented package, in backticks).

• dep_name (str) – the tracked distribution ("click").

• show_spec (bool) – add a Spec column with each range’s raw specifier.

Return type:

str

Returns:

rendered markdown table, or "" when nothing was collected.

class click_extra.sphinx.matrix.MatrixDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SphinxDirective

Render a package’s compatibility matrix for a given axis.

{matrix} python renders the interpreter matrix (release ranges × Python versions). {matrix} <distribution> (like {matrix} click) renders a dependency matrix (release ranges × that dependency’s versions, from its requirement specifier across the git history). Both emit a GitHub-flavored table parsed by the host document’s parser, so it lands as a real <table>.

The table normally lives inside the block as its content, kept current by the offline updater (update_matrix_blocks(), exposed as the click-extra refresh-directives command). Rendering that embedded copy needs no git access at build time, so shallow clones and read-only build hosts still show the matrix. An empty block falls back to generating from the working tree’s git tags, so a freshly authored block renders before its first refresh.

Argument: the axis, python or a distribution name.

Options:

• :package: — header column label. Defaults to the repository name.

• :path: — git working tree to walk, absolute or relative to the documented project’s git root. Defaults to that git root.

• :version-floor: — drop release rows below this package version.

• :tag-pattern: — regex selecting release tags. Defaults to DEFAULT_TAG_PATTERN.

• :python-floor: — (python axis) drop Python columns below X.Y.

• :show-spec: — (dependency axis) add a raw-specifier Spec column.

The git fallback is resilient: a missing git binary, a non-repository path, or a tag-less repository logs a build warning and renders nothing rather than aborting the build.

has_content = True

May the directive have content?

required_arguments = 1

Number of required directive arguments.

optional_arguments = 0

Number of optional arguments after the required arguments.

option_spec: ClassVar[OptionSpec] = {'package': <function unchanged>, 'path': <function unchanged>, 'python-floor': <function unchanged>, 'show-spec': <function flag>, 'tag-pattern': <function unchanged>, 'version-floor': <function unchanged>}

Mapping of option names to validator functions.

run()

Return type:

list[Node]

click_extra.sphinx.matrix.setup(app)

Register the always-on matrix directive on app.

Called from click_extra.sphinx.setup() so projects only need to list "click_extra.sphinx" in their extensions. Unlike the click:* / python:* families, the directive is registered unconditionally: it runs a canned matrix generator, not user-supplied Python, so it needs no opt-in.

Return type:

None

click_extra.sphinx.matrix.update_matrix_blocks(paths, *, check=False)

Refresh every {matrix} block in the given Markdown sources.

Walks paths (files, or directories recursed for *.md), regenerates each block’s table from its axis and options, and rewrites the file when its content changed. In check mode nothing is written; the return value still lists the files that would change, so a caller can exit non-zero to flag stale documentation in CI.

Return type:

list[Path]

Returns:

the files whose {matrix} blocks were (or, under check, would be) updated.