click_extra.sphinx package¶

… py:module:: click_extra.sphinx

Helpers and utilities for Sphinx.

… py:function:: setup(app)

module:

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

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\~sphinx.util.typing.ExtensionMetadata``

Submodules¶

click_extra.sphinx.alerts module¶

… py:module:: click_extra.sphinx.alerts

Utilities to convert GitHub alerts into MyST admonitions for Sphinx.

… seealso:: - 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 <https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/>.

… py:data:: GITHUB_ALERT_PATTERN

module:

click_extra.sphinx.alerts

value:

re.compile(‘^\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$’)

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

… py:data:: QUOTE_PREFIX_PATTERN

module:

click_extra.sphinx.alerts

value:

re.compile(‘^(\s*)((?:>\s*)+)(.*)$’)

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

… py:data:: CODE_FENCE_PATTERN

module:

click_extra.sphinx.alerts

value:

re.compile(‘^(\s*)(`{3,}|~{3,})(.*)$’)

Regex pattern to match code fence opening/closing lines.

… py:data:: INDENTED_CODE_BLOCK_PATTERN

module:

click_extra.sphinx.alerts

value:

re.compile(‘^( {4}|\t)’)

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

… py:class:: Alert(alert_type, indent, depth, has_nested=False, opening_line_index=0)

module:

click_extra.sphinx.alerts

Bases: :py:class:object

Represents a GitHub alert being processed.

… py:attribute:: Alert.alert_type

module:

click_extra.sphinx.alerts

type:

str

… py:attribute:: Alert.indent

module:

click_extra.sphinx.alerts

type:

str

… py:attribute:: Alert.depth

module:

click_extra.sphinx.alerts

type:

int

… py:attribute:: Alert.has_nested

module:

click_extra.sphinx.alerts

type:

bool

value:

click_extra.sphinx.click module¶

… py:module:: click_extra.sphinx.click

Sphinx rendering of CLI based on Click Extra.

… seealso:: These directives are based on Pallets' Sphinx Themes <https://github.com/pallets/pallets-sphinx-themes/blob/main/src/pallets_sphinx_themes/themes/click/domain.py>, released under a BSD-3-Clause license <https://github.com/pallets/pallets-sphinx-themes/blob/main/LICENSE.txt>.

   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.

… py:data:: RST_INDENT

module:

click_extra.sphinx.click

value:

’ ’

The indentation used for rST code blocks lines.

… py:class:: TerminatedEchoingStdin(input, output)

module:

click_extra.sphinx.click

Bases: :py:class:~click.testing.EchoingStdin

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

meth:: ClickRunner.invoke adds when terminate_input=True.

… py:function:: patch_subprocess()

module:

click_extra.sphinx.click

Patch subprocess to work better with :meth:ClickRunner.invoke.

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

… py:class:: ClickRunner()

module:

click_extra.sphinx.click

Bases: :py:class:~click.testing.CliRunner

A sub-class of :class: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.

… py:method:: ClickRunner.isolation(*args, **kwargs)

module:

click_extra.sphinx.click

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 :meth:invoke method.

param input:

the input stream to put into sys.stdin.

param env:

the environment overrides as dictionary.

param color:

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

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

… versionchanged:: 8.2 Always returns the <stderr> stream.

… versionchanged:: 8.0 <stderr> is opened with errors="backslashreplace" instead of the default "strict".

… versionchanged:: 4.0 Added the color parameter.

… py:method:: ClickRunner.invoke(cli, args=None, prog_name=None, input=None, terminate_input=False, env=None, _output_lines=None, **extra)

module:

click_extra.sphinx.click

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

type terminate_input:

param terminate_input:

Whether to display ^D after a list of input.

type _output_lines:

param _output_lines: