click_extra.sphinx package

Helpers and utilities for Sphinx.

click_extra.sphinx.setup(app)

Register extensions to Sphinx.

• New directives, augmented with ANSI coloring.

• Support for GitHub alerts syntax in included and regular source files.

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.

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.

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.

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.

class click_extra.sphinx.click.ClickRunner

Bases: ExtraCliRunner

A sub-class of click.testing.CliRunner with additional features.

This class inherits from click_extra.testing.ExtraCliRunner to have full control of contextual color settings by the way of the color parameter. It also produce unfiltered ANSI codes so that the Directive sub-classes below can render colors in the HTML output.

force_color: bool = True

Force color rendering in invoke calls.

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 ExtraCliRunner.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[dict[str, Callable[[str], Any]]] = {'caption': <function unchanged_required>, 'class': <function class_option>, 'dedent': <function optional_int>, 'emphasize-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.

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.

property runner: ClickRunner

Get or create the ClickRunner instance associated with a document.

Creates one runner per document.

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.

property code_block_options: list[str]

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

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)

Render the code block with the source code and results.

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.DeprecatedExampleDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: SourceDirective

Deprecated alias for SourceDirective.

Deprecated since version 7.3.0: Use click:source instead of click:example.

run()

Return type:

list[Node]

class click_extra.sphinx.click.ClickDomain(env)

Bases: Domain

Setup new directives under the same click namespace:

• click:source which renders a Click CLI source code

• click:example, an alias to click:source (deprecated)

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

name = 'click'

domain name: should be short, but unique

label = 'Click'

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

directives: dict[str, type[Directive]] = {'example': <class 'click_extra.sphinx.click.DeprecatedExampleDirective'>, 'run': <class 'click_extra.sphinx.click.RunDirective'>, 'source': <class 'click_extra.sphinx.click.SourceDirective'>}

directive name -> directive class

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

Close and remove the ClickRunner instance once the document has been read.

Return type:

None