tests.sphinx package

Submodules

tests.sphinx.conftest module

Fixtures and helpers for Sphinx tests.

Separated from the root tests/conftest.py so that the Sphinx dependency (and its ecosystem: myst-parser, docutils, etc.) is only imported when running the tests in this subdirectory. Downstream packagers can skip these tests with --ignore=tests/sphinx without affecting the rest of the test suite.

tests.sphinx.conftest.MYST_HAS_NATIVE_ALERTS = True

Flip-switch reused by tests to branch between the two alert rendering paths: click_extra’s regex converter (pre-5.1) and myst-parser’s native "alert" extension (>=5.1). Both paths must produce the same admonition HTML.

class tests.sphinx.conftest.FormatType(*values)

Bases: Enum

Sphinx document format types and their file extensions.

RST = '.rst'

MYST = '.md'

class tests.sphinx.conftest.SphinxAppWrapper(app, format_type)

Bases: object

Wrapper around Sphinx application with additional testing methods.

classmethod create(format_type, tmp_path, return_srcdir=False, enable_exec_directives=True)

Factory method to create a SphinxAppWrapper with given format.

enable_exec_directives opts the test app into the click:* and python:* directive families. Defaults to True for every fixture-built app because the test suite primarily exercises those directives. Tests that verify the off-by-default production gate flip the flag back to False explicitly.

Return type:

Generator[SphinxAppWrapper | tuple[SphinxAppWrapper, Path], None, None]

build_document(content)

Build a Sphinx document with content and return the HTML output.

Automatically detects the format from the app configuration and uses the appropriate file extension (.rst or .md).

Return type:

str | None

generate_test_content(test_case)

Generate content for a test case based on the app’s format type.

Return type:

str

tests.sphinx.conftest.sphinx_app(request, tmp_path)

Create a Sphinx application for testing.

tests.sphinx.conftest.sphinx_app_for_format(request, tmp_path)

sphinx_app variant whose format is supplied by the caller.

Identical to sphinx_app() but without the default params: the FormatType is taken from the test’s indirect parametrization. A params-bearing fixture cannot also be parametrized by a test (pytest rejects it as a duplicate parametrization), so a test that drives the format per case parametrizes this variant instead, usually through format_params().

tests.sphinx.conftest.sphinx_app_rst(tmp_path)

Create a Sphinx application for testing RST format only.

The click:* and python:* directive families are enabled so tests can exercise them. Tests that explicitly verify the off-by- default opt-in gate construct their own app via SphinxAppWrapper.create() with enable_exec_directives=False.

tests.sphinx.conftest.sphinx_app_myst(tmp_path)

Create a Sphinx application for testing MyST format only.

The click:* and python:* directive families are enabled: see sphinx_app_rst() for the rationale.

tests.sphinx.conftest.sphinx_app_myst_with_include(tmp_path)

Create a Sphinx application for testing MyST format with include files.

class tests.sphinx.conftest.DirectiveTestCase(name, format_type=None, source_block=None, run_block=None, document=None, html_matches=None)

Bases: object

Test case data for directive tests.

name: str

format_type: FormatType | None = None

source_block: str | None = None

run_block: str | None = None

document: str | None = None

html_matches: Sequence[str] | str | None = None

tests.sphinx.conftest.format_params(*test_cases)

Pair each test case with every document format it is written for.

Feeds the indirect parametrization of sphinx_app_for_format(), so a case is only ever built by an app whose format it can render: a case pinned to a FormatType yields that format alone, a format-agnostic one yields a parameter per format.

Return type:

tuple[ParameterSet, ...]

tests.sphinx.conftest.unescape_quotes(text)

Replace quote entities with bare quotes, so both escapings compare equal.

Pygments 2.21.0 replaced its escape_html() helper with html.escape(value, quote=False). Token text carries bare " and ' since then, where older releases produced " and '. Both forms render the same, and the pygments extra declares a floor spanning that release, so HTML fragments are compared with quotes normalized.

Return type:

str

tests.sphinx.conftest.python_block(*lines)

Build expected Python highlight block.

Return type:

str

tests.sphinx.conftest.shell_block(*lines)

Build expected shell session block.

Return type:

str

tests.sphinx.conftest.admonition_block(admonition_type, content)

Build expected admonition block.

Parameters:

• admonition_type (str) – The type of admonition (note, tip, warning, etc.)

• content (str) – The inner HTML content of the admonition (without the title)

Return type:

str

tests.sphinx.test_sphinx module

Fixtures and utilities for Sphinx testing.

tests.sphinx.test_sphinx.test_import_without_myst_parser()

The extension imports for a reST-only project, which installs no myst-parser.

The sphinx extra does not declare myst-parser and Sphinx does not depend on it, so a hard import of it in click_extra.sphinx breaks such a project outright.

tests.sphinx.test_sphinx.test_sphinx_extension_setup(sphinx_app)

Test that the Sphinx extension is properly loaded.

tests.sphinx.test_sphinx.test_resolve_any_xref(sphinx_app)

Test that resolve_any_xref is implemented and returns an empty list.

See also

https://github.com/kdeldycke/click-extra/issues/1502

tests.sphinx.test_sphinx_alerts module

Tests for GitHub alert syntax conversion in Sphinx with MyST parser.

tests.sphinx.test_sphinx_alerts.test_all_alert_types(alert_type)

Test all supported alert types are converted correctly.

tests.sphinx.test_sphinx_alerts.test_alert_conversion(text, expected)

Test GitHub alerts are converted to MyST admonitions.

When expected is None, no conversion should occur.

tests.sphinx.test_sphinx_alerts.test_sphinx_integration(sphinx_app_for_format, test_case)

Integration-critical tests that verify Sphinx rendering behavior.

tests.sphinx.test_sphinx_alerts.test_github_alert_no_colon_fence(tmp_path)

Test that ConfigError is raised when colon_fence is not enabled.

tests.sphinx.test_sphinx_alerts.test_github_alert_in_included_files(sphinx_app_myst_with_include, included_files, main_content, expected_fragments, unexpected_fragments)

Test GitHub alerts in included files with various configurations.

tests.sphinx.test_sphinx_click module

Tests for Sphinx directives click:source and click:run in rST and MyST formats.

tests.sphinx.test_sphinx_click.test_directive_functionality(sphinx_app_for_format, test_case)

Test standard directive functionalities in each format a case targets.

tests.sphinx.test_sphinx_click.test_directive_option_format(sphinx_app_rst)

rST will fail to render if an :option: is not followed by an empty line.

tests.sphinx.test_sphinx_click.test_directive_option_language_override(sphinx_app)

Test that language override works for click:run directive.

tests.sphinx.test_sphinx_click.test_sphinx_directive_state_persistence(sphinx_app)

Test that state persists between declare and run directives in real Sphinx.

tests.sphinx.test_sphinx_click.test_directive_variable_conflict(var_name, sphinx_app_for_format, content, directive_lineno, error_lineno)

Test that variable conflicts are properly detected in real Sphinx environment.

tests.sphinx.test_sphinx_click.GENERATED_BLOCK_ANCHOR = 'from click_extra import command, echo'

First body line of the GENERATED_BLOCK_LINE_CASES documents below.

The line a generated block is expected to be attributed to, located in the document itself so editing a case moves the expectation with it.

tests.sphinx.test_sphinx_click.test_generated_block_is_attributed_to_the_directive_body(sphinx_app_for_format, test_case)

A block a directive generates is attributed to its first body line.

The generated lines exist nowhere in the document, so the parser has to be told which document line to hang a diagnostic raised inside them on. Both formats must answer the same way, and neither is free to fall back on its own default: docutils numbers an unlabelled block from the top of the file, and myst-parser measures its offsets from the directive rather than the document.

The last two cases pin the content_offset inflation click_extra.sphinx.click.MYST_CONTENT_OFFSET_INFLATED_MAX documents, which only fires on a directive carrying both an option block and a body ending in blank lines.

tests.sphinx.test_sphinx_click.test_exit_exception_percolate(sphinx_app)

Test directives that handle command errors and exit codes.

tests.sphinx.test_sphinx_click.test_clickrunner_forces_color(monkeypatch)

ClickRunner forces FORCE_COLOR so Rich-based CLIs colorize under NO_COLOR.

The runner already passes color=True (Click’s color system). But rich-click renders help through Rich’s Console, gated on FORCE_COLOR, which color=True never reaches. The runner therefore also forces FORCE_COLOR (clearing the disabling vars) around the executed command, then restores the environment.

tests.sphinx.test_sphinx_click.test_clickrunner_capture_mode_controls_fileno(capture, renders)

ClickRunner(capture=...) decides whether a fileno-writing CLI renders.

Click’s "sys" mode backs the captured stream with an in-memory buffer whose fileno() raises io.UnsupportedOperation, so a documented command that re-opens its descriptor (a common UTF-8-on-Windows guard) aborts. "fd" (the default on Unix, also exposed as the click_extra_run_capture conf.py value) backs it with a real descriptor, so the command renders. On Windows, where fd-backed streams are not supported, the default falls back to "sys".

tests.sphinx.test_sphinx_click.test_program_from_command_line(command_line, expected)

Only an interpreter prefix is dropped from a displayed command line.

tests.sphinx.test_sphinx_click.test_clickrunner_keeps_a_multi_word_prog_name(monkeypatch)

A subcommand-shaped program name reaches the command it runs, whole.

tests.sphinx.test_sphinx_click.test_clickrunner_prompt_inlines_environment_assignments(monkeypatch)

Variables are set on the invocation, the way the runner applies them.

CliRunner scopes env to the one call, so an export line would advertise a persistence the next block does not inherit.

tests.sphinx.test_sphinx_click.test_clickrunner_prompt_quotes_a_spaced_argument(monkeypatch)

An argument holding spaces stays the single token a reader must type.

tests.sphinx.test_sphinx_click.test_clickrunner_hide_prompt_drops_the_invocation(monkeypatch)

_show_prompt=False leaves the output alone and drops the line above it.

tests.sphinx.test_sphinx_click.test_click_run_prompt_options(sphinx_app_myst, options, prompted)

:show-prompt: / :hide-prompt: gate the invocation line.

tests.sphinx.test_sphinx_click.test_click_run_hide_prompt_reaches_the_screenshot(sphinx_app_myst)

A capture is drawn from the same lines, so it loses the prompt too.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_writes_the_asset(sphinx_app_myst)

:screenshot: writes the capture beside the documentation.

The image is a side effect: the page keeps its results code block, which inside Sphinx beats an image by staying selectable and searchable.

tests.sphinx.test_sphinx_click.ANIMATED_SOURCE = '\n    ```{click:source}\n    :hide-source:\n    from click_extra import SPINNERS, Spinner, Style, command, echo\n\n    @command\n    def greet():\n        echo("Hello, papaya!")\n\n    steeping = Spinner("Steeping", spinner=SPINNERS["moon"], style=Style(fg="green"))\n    ```\n'

A spinner and a CLI, seeded for the animated-capture blocks below.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_stacks_a_spinner(sphinx_app_myst)

:screenshot-animate: draws every frame of the spinner it names.

The frames and the interval are taken off the spinner itself, so the picture and the animation cannot disagree about either.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_defines_every_class_it_uses(sphinx_app_myst)

No frame names a class the animated capture leaves undefined.

A frame whose rules are missing does not vanish: it falls back to the presentation attributes and draws in the wrong face and the wrong color, which reads as the animation resetting its styling once a cycle.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_accepts_bare_frames(sphinx_app_myst)

A sequence of texts animates too, timed by :screenshot-interval:.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_bare_frames_need_an_interval(sphinx_app_myst)

Bare frames carry no timing of their own, so one has to be stated.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_rejects_a_foreign_subject(sphinx_app_myst)

Something that is neither a spinner nor frames fails the build.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_is_deterministic(sphinx_app_myst)

A declared subject composes the same lines on every build.

This is what lets an animated capture be committed at all: a recording would time its frames a little differently on every run and dirty the tree.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_rewrites_a_declared_asset(sphinx_app_myst)

A declared animation is regenerated on every build, like any capture.

It composes the same lines every time, so rewriting costs nothing and is what keeps the asset from drifting away from the code. Gating the write on what the animation is would freeze out every change to how it is drawn.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_animate_carries_a_presentation_change(sphinx_app_myst)

Restating how an animation is drawn reaches the committed asset.

The frames are untouched by a margin, so nothing about what the animation is moves. The picture still has to change.

tests.sphinx.test_sphinx_click.RECORDED_SOURCE = '\n    ```{click:source}\n    :hide-source:\n    from click_extra.recording import Frame\n\n    kettle = [Frame("filling", 0.2), Frame("boiled", 0.2)]\n    ```\n'

A stand-in recording: frames carrying their own durations, as one does.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_record_writes_once(sphinx_app_myst)

A recorded animation is written the first time and then left alone.

Which spinner glyph pairs with which screen is settled by the scheduler, so a recording cannot be reproduced and rewriting it would dirty the working tree for nothing anyone did.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_record_holds_its_last_frame(sphinx_app_myst)

A recording pauses on its final screen before starting over.

An animation that ends somewhere is worth reading, and a loop restarting the instant it arrives never lets anyone.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_hold_overrides_the_pause(sphinx_app_myst)

:screenshot-hold: states the pause a page would rather have.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_blank_closes_the_cycle(sphinx_app_myst)

A recording ends on an empty beat, so the loop’s turnover is visible.

Without it, a loop jumping from its last frame back to its first reads as one long animation doing something odd rather than as a repetition.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_speed_scales_the_recorded_frames(sphinx_app_myst)

:screenshot-speed: replays faster, leaving the pauses as stated.

The pauses are how long a reader is given, not part of what is replayed, so they are stated in real seconds and speed does not touch them.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_emphasize_lines_bands_a_still(sphinx_app_myst)

:screenshot-emphasize-lines: draws a band behind the lines it names.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_emphasize_lines_bands_an_animation(sphinx_app_myst)

A band marks a row of the screen, so an animation keeps it throughout.

Drawn once behind every frame rather than per frame: the emphasis is on the row, not on whatever a given frame happened to put there.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_emphasize_lines_rejects_a_line_that_is_not_there(sphinx_app_myst)

Naming a line the capture never drew fails the build rather than passing.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_background(sphinx_app_myst)

:screenshot-background: draws the capture on the chrome it names.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_columns_auto(sphinx_app_myst)

:screenshot-columns: auto widens the image to what the block printed.

Click wraps a CLI’s own text at its fixed width whatever the option says. What it decides is the picture, and a line the CLI never wrapped (the prompt of a long invocation) is the one that needs the room.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_columns_rejects_an_unusable_width(value)

A width narrower than the floor, or no width at all, is a build error.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_frame_options(sphinx_app_myst)

The :screenshot-*: options restate the window, the title included.

The hex color is quoted because a directive’s options are read as YAML, where an unquoted # opens a comment and leaves the option empty.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_preset_swaps_the_prompt(sphinx_app_myst)

A capture drawn as another terminal prompts the way that one does.

A block runs under a documentation build, so its own prompt is this platform’s $. The picture is of a Windows terminal, whose shell prompts with something else entirely.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_preset_defaults_to_the_project_wide_one(sphinx_app_myst)

A project drawing every capture as the same terminal states it once.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_carries_no_watermark_by_default(sphinx_app_myst)

A capture a build rewrites carries no release number to go stale.

The screenshot command credits click-extra on every image it writes. A block’s image is regenerated and committed on every build, so the same mark would rewrite every asset the day the release it names changes.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_watermark(sphinx_app_myst)

A project wanting its captures credited states the line once.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_opacity(sphinx_app_myst)

A see-through window lets the page it is laid on show through its body.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_opacity_rejects_what_is_not_one(argument)

Anything outside the zero-to-one range fails the build instead of clamping.

tests.sphinx.test_sphinx_click.test_click_run_screenshot_background_rejects_an_unknown_chrome()

A typo names the chromes it could have been, instead of drawing a default.

tests.sphinx.test_sphinx_click.test_click_run_mirror_region_round_trips()

:mirror: inserts an image link below the fence, then leaves it alone.

tests.sphinx.test_sphinx_click.test_click_run_mirror_needs_both_options()

A block missing either option gets no region.

:screenshot: alone maintains an asset some other surface embeds, without putting it on this page; :mirror: alone has no capture to point at.

tests.sphinx.test_sphinx_click.test_click_run_mirror_skips_a_nested_example()

A click:run shown inside a longer fence is documentation, not a block.

tests.sphinx.test_sphinx_click.test_click_source_screenshot_pictures_its_own_code(sphinx_app_myst)

A source block’s :screenshot: draws the code it declares.

A directive that runs something has output worth committing; one that only declares code has none, so its subject is the code itself.

tests.sphinx.test_sphinx_click.test_click_source_screenshot_takes_a_syntax_style(sphinx_app_myst)

:screenshot-syntax-style: repaints the window along with the code.

tests.sphinx.test_sphinx_click.test_click_source_screenshot_bands_its_emphasized_lines(sphinx_app_myst)

:emphasize-lines: marks the same lines on the page and in the image.

A source block has one content, so saying it twice would be the surprise.

tests.sphinx.test_sphinx_click.test_click_source_screenshot_is_deterministic(sphinx_app_myst)

Two builds of one source block write the same bytes.

Nothing here runs a command or reads a clock, so a committed asset stays put and leaves the working tree clean.

tests.sphinx.test_sphinx_click.test_click_source_mirror_shows_the_snippet()

A source block mirrors its capture the way a run block does.

Same marker pair, same derivation from the :screenshot: name: what changed is only which directives are allowed to ask.

tests.sphinx.test_sphinx_click.test_python_render_mirror_is_left_to_its_own_refresher()

python:render keeps the one :mirror: that means something else.

It mirrors the markup the block generated, and a second refresher writing that region would undo the first on every alternate run.

tests.sphinx.test_sphinx_click_tree module

Tests for the click:tree Sphinx directive.

tests.sphinx.test_sphinx_click_tree.KITCHEN_CLI = '```{click:source}\n:hide-source:\nfrom click import command, echo, group, option\n\n@group\ndef kitchen():\n    """Manage kitchen tools and recipes."""\n\n@kitchen.command\n@option("--minutes", type=int, default=5)\ndef boil(minutes):\n    """Boil water for tea."""\n    echo(f"Boiling for {minutes} minutes.")\n\n@kitchen.group\ndef pantry():\n    """Inspect pantry contents."""\n\n@pantry.command\ndef jars():\n    """List jars on the shelf."""\n    echo("Olives, honey, pickles.")\n```\n'

Toy CLI reused across tests. Defines a multi-level group so the walk exercises the recursive descent into nested click.Group commands.

tests.sphinx.test_sphinx_click_tree.test_click_tree_renders_summary_table_and_help_blocks(sphinx_app_myst)

The directive expands into a GFM table + one help capture per command.

tests.sphinx.test_sphinx_click_tree.test_click_tree_inline_import_in_body(sphinx_app_myst)

The directive body runs as a preamble, so a seed click:source is optional.

tests.sphinx.test_sphinx_click_tree.test_click_tree_no_table_and_no_root(sphinx_app_myst)

:no-table: and :no-root: drop the summary table and root block.

tests.sphinx.test_sphinx_click_tree.test_click_tree_max_depth_truncates_walk(sphinx_app_myst)

:max-depth: 1 stops the walk at one level below the root.

tests.sphinx.test_sphinx_click_tree.test_click_tree_label_and_anchor_prefix_override(sphinx_app_myst)

:label-prefix: and :anchor-prefix: override the defaults.

tests.sphinx.test_sphinx_click_tree.test_click_tree_errors_on_non_command(sphinx_app_myst)

Resolving the argument to a non-Command raises a clear directive error.

tests.sphinx.test_sphinx_click_tree.test_click_tree_errors_on_unknown_name(sphinx_app_myst)

An expression that can’t be evaluated raises a clear directive error.

tests.sphinx.test_sphinx_click_tree.test_click_tree_errors_in_rst(sphinx_app_rst)

click:tree raises a clear error when used in an rST document.

tests.sphinx.test_sphinx_click_tree.test_click_tree_heading_offset_defaults_to_top_level(sphinx_app_myst)

Below a single # Doc title the root renders at h2.

Preserves the historical default behavior: a directive at the document body (inside the title’s h1 section) emits its root one level below.

tests.sphinx.test_sphinx_click_tree.test_click_tree_heading_offset_adapts_to_surrounding_section(sphinx_app_myst)

Nested inside an h3 section, the root renders at h4.

The default heading offset is computed from state.memo.section_level so the document outline stays consistent regardless of where the directive is placed.

tests.sphinx.test_sphinx_click_tree.test_click_tree_heading_offset_explicit_override(sphinx_app_myst)

An explicit :heading-offset: wins over the auto-detected default.

Surrounding headings establish a deep level so the override’s effect is clearly observable in the rendered HTML (without MyST normalizing skipped heading levels).

tests.sphinx.test_sphinx_manpages module

Tests for click_extra.sphinx.manpages.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_writes_tree_into_outdir(tmp_path)

An entry with just script writes the whole tree under man/.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_honors_prog_name_and_output_dir(tmp_path)

An entry can override both the basename and the subdirectory.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_skips_non_html_builder(tmp_path)

Non-HTML builders (like linkcheck) must not emit man pages.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_empty_config_is_noop(tmp_path)

An empty list leaves the build untouched.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_skips_entry_without_script(tmp_path)

An entry missing script is skipped (logged as a warning) instead of aborting the build.

tests.sphinx.test_sphinx_manpages.test_manpages_module_help_documents_config_shape()

The module docstring spells out every supported key.

A safety net against silent removal: distributors and downstream projects depend on the docstring as the canonical reference, since it is what help(click_extra.sphinx.manpages) prints.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_emits_html_siblings(tmp_path)

When a renderer is available, every .1 gets a .1.html next to it whose body carries the section headings from the source roff.

tests.sphinx.test_sphinx_manpages.test_manpages_hook_respects_render_html_opt_out(tmp_path)

render_html=False skips the HTML pass even when a renderer is present, keeping the build to roff only.

tests.sphinx.test_sphinx_manpages.test_manpages_directive_renders_one_link_per_command(tmp_path)

The directive emits a bullet list with one entry per (sub)command of every script declared in click_extra_manpages.

tests.sphinx.test_sphinx_manpages.test_manpages_directive_links_follow_the_builder_layout(tmp_path, builder, page_file, prefix)

Links resolve from wherever the builder publishes the page.

tests.sphinx.test_sphinx_manpages.test_manpages_directive_links_survive_a_shared_doctree_cache(tmp_path, builder, page_file, prefix)

A second builder reusing pickled doctrees still gets its own layout.

Sphinx does not invalidate its doctree cache when the builder changes, so the directive never re-runs on the second pass. A link resolved at parse time would keep the first builder’s layout and point at nothing.

tests.sphinx.test_sphinx_manpages.test_manpages_directive_is_noop_when_config_empty(tmp_path)

An empty config means no bullet list, no warning, build still finishes.

tests.sphinx.test_sphinx_manpages.test_manpages_directive_renders_inline_literals_as_code(tmp_path)

Inline reST literals in a command’s short_help land as <code> spans in the rendered index, not as raw backticks rendered like quotes.

tests.sphinx.test_sphinx_python module

Tests for the python:* Sphinx directive family.

Covers python:source, python:run, and the three render variants:

• python:render (host parser)

• python:render-myst (forced MyST, regardless of host)

• python:render-rst (forced reST, regardless of host)

tests.sphinx.test_sphinx_python.test_python_run_renders_stdout(sphinx_app_myst)

python:run captures print output and renders it in a code block.

tests.sphinx.test_sphinx_python.test_python_source_seeds_namespace_for_python_run(sphinx_app_myst)

python:source runs silently; a follow-up python:run reuses its imports.

tests.sphinx.test_sphinx_python.test_python_run_language_override(sphinx_app_myst)

:language: overrides the default text lexer for the result block.

tests.sphinx.test_sphinx_python.test_python_run_emphasize_lines_split(sphinx_app_myst)

:emphasize-lines: highlights source only; :emphasize-result-lines: highlights result only: independently, on the same block.

tests.sphinx.test_sphinx_python.test_python_render_passes_block_level_html(sphinx_app_myst)

python:render passes block-level raw HTML through unchanged.

A naked print('<div>...</div>') should reach the rendered page without any {raw} html wrapping. Locks down the natural-form pattern so a future MyST upgrade or extension reordering can’t silently regress it.

tests.sphinx.test_sphinx_python.test_python_render_host_myst_injects_table(sphinx_app_myst)

python:render parses captured stdout with the host (MyST) parser.

tests.sphinx.test_sphinx_python.test_python_render_host_myst_injects_heading(sphinx_app_myst)

A heading printed by python:render becomes a real heading node.

tests.sphinx.test_sphinx_python.test_python_render_host_rst_injects_admonition(sphinx_app_rst)

python:render in an rST host: stdout is parsed as reST.

tests.sphinx.test_sphinx_python.test_python_render_myst_in_rst_host(sphinx_app_rst)

python:render-myst forces MyST parsing inside an rST host document.

This is the headline use case: an rST file embeds Python that prints MyST markup and the directive parses it as MyST regardless of host.

tests.sphinx.test_sphinx_python.test_python_render_rst_in_myst_host(sphinx_app_myst)

python:render-rst forces reST parsing inside a MyST host document.

tests.sphinx.test_sphinx_python.test_python_render_myst_in_myst_host_still_works(sphinx_app_myst)

python:render-myst works in MyST hosts too; it always picks MyST.

tests.sphinx.test_sphinx_python.test_python_render_rst_in_rst_host_still_works(sphinx_app_rst)

python:render-rst works in rST hosts too; it always picks reST.

tests.sphinx.test_sphinx_python.test_exec_directives_disabled_by_default(tmp_path)

Without the opt-in flag, click:* and python:* are not registered.

The Sphinx build still succeeds but neither family’s directive body is ever executed. This is the desired security default: a project that adds click_extra.sphinx to its extensions list does not silently gain build-time arbitrary Python execution.

The exact rendering of an unrecognized directive is parser-dependent (MyST silently swallows it; reST emits a system message), so the assertion focuses on the security-relevant invariant: the directive body’s print output never reaches the rendered HTML.

tests.sphinx.test_sphinx_python.test_exec_directives_enabled_with_opt_in(tmp_path)

Setting click_extra_enable_exec_directives = True activates them.

tests.sphinx.test_sphinx_python.test_python_runner_isolated_from_click_runner(sphinx_app_myst)

The Python and Click runners hold independent namespaces.

tests.sphinx.test_sphinx_python.test_mirror_src_rewrite_inserts_region()

A mirror-src comment with no region yet gets one, generator kept hidden.

tests.sphinx.test_sphinx_python.test_mirror_src_rewrite_is_idempotent()

Re-running over an already-filled mirror-src region is a no-op.

tests.sphinx.test_sphinx_python.test_mirror_src_via_update_mirror_blocks(tmp_path)

The offline refresher fills a mirror-src region, then round-trips clean.

tests.sphinx.test_sphinx_python.test_mirror_src_rewrite_skips_example_nested_in_code_block()

A mirror-src comment shown inside a longer code-block fence is never run.

tests.sphinx.test_sphinx_python.test_mirror_rewrite_inserts_region()

A mirror block with no region yet gets one inserted below the fence.

tests.sphinx.test_sphinx_python.test_mirror_rewrite_is_idempotent()

Re-running over an already-mirrored document is a no-op.

tests.sphinx.test_sphinx_python.test_mirror_rewrite_replaces_stale_region()

A stale region is refreshed from the block’s current output.

tests.sphinx.test_sphinx_python.test_mirror_rewrite_skips_example_nested_in_code_block()

A mirror block shown inside a longer code-block fence is never executed.

tests.sphinx.test_sphinx_python.test_python_render_mirror_renders_fresh_without_touching_source(sphinx_app_myst)

:mirror: renders the table once; the build never writes to the source.

tests.sphinx.test_sphinx_python.test_update_mirror_blocks_populates_and_idempotent(tmp_path)

The offline refresher inserts the region, then round-trips clean.

tests.sphinx.test_sphinx_python.test_update_mirror_blocks_check_mode(tmp_path)

check=True reports the stale file without writing it.

tests.sphinx.test_sphinx_python.test_update_mirror_blocks_imports_sibling_module(tmp_path)

A mirror block imports a helper module living next to the page.

Matches the Sphinx build, where the conf.py directory is importable, so a docs_update.py-style generator module works offline too. The path entry is scoped to the execution and removed afterwards.

tests.sphinx.test_sphinx_python.test_refresh_directives_cli_refreshes_mirror_blocks(tmp_path)

click-extra refresh-directives covers mirror regions too.

tests.sphinx.test_sphinx_python.test_python_render_mirror_show_source_still_single_table(sphinx_app_myst)

:mirror: :show-source: shows the Python but still renders one table.