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.

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.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

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] = {'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