Python directives

The Sphinx extension also runs arbitrary Python at build time. The python:* family renders what a block printed, as a code block or as live document content. The matrix directive renders a release compatibility table from a fixed generator.

See also

Both families need the click_extra.sphinx extension enabled, and the python:* one needs the build-time execution opt-in on top. The Sphinx setup covers each step.

python:* directives

Click Extra also adds five general-purpose Python execution directives, registered under a separate python domain (distinct from Sphinx’s built-in py domain for documenting API objects):

Directive

Purpose

python:source

Define and show a Python source block, executed silently. Use it to teach readers what a snippet looks like and to seed imports/variables for follow-up blocks.

python:run

Execute a Python block and render its captured stdout in a code block. Output language defaults to text; override with :language: for structured output (json, html, yaml, etc.).

python:render

Execute a Python block and parse its captured stdout as live document content using the host file’s parser. Generated tables, headings, admonitions, and cross-references become first-class document nodes, not a code block.

python:render-myst

Execute a Python block and parse its captured stdout as MyST, regardless of host. Lets a .rst document embed MyST-generated content.

python:render-rst

Execute a Python block and parse its captured stdout as reST, regardless of host. Lets a .md document embed reST-generated content.

These complement the Click directives: click:run is for showing simulated CLI sessions; python:run is for showing arbitrary Python output; the python:render* family is for inline content generation, replacing the regenerator-script + marker-region pattern many projects use to keep auto-tables in sync.

Hint

This project eats its own dog food: the ANSI lexer table in pygments.md is rendered live at build time by an inline python:render block that imports LEXER_MAP and prints a Markdown table. Read the exact source lines on GitHub for a real-world example of replacing a regenerator script with a one-block inline build-time computation.

Pick the right render

Directive

Parser used for captured stdout

When to use

python:render

Whatever parser owns the host source file

Generated markup matches the host file format.

python:render-myst

MyST, regardless of host

Embed MyST-generated content in a .rst host.

python:render-rst

reST, regardless of host

Embed reST-generated content in a .md host.

python:render reuses the host state machine, so cross-references and Sphinx-aware roles resolve naturally. The forced-parser variants (render-myst, render-rst) parse into a fresh sub-document and graft the resulting nodes back into the page.

python:render: docs as code

Tip

The strongest use case is replacing a docs/docs_update.py script that walks an in-process registry, renders Markdown, and rewrites a region of a .md file between <!-- start --> / <!-- end --> markers. With python:render, the same code lives inline in the page itself and runs at build time. The rendered HTML is always current because the source-of-truth registry is queried on every build.

Render the live list of Python’s built-in modules as a Markdown table, executed by Sphinx at build time:

```{python:render}
import sys
print("| Module | Type |")
print("|--------|------|")
for name in sorted(sys.builtin_module_names)[:5]:
    print(f"| `{name}` | built-in |")
```
.. python:render::

    import sys
    print("| Module | Type |")
    print("|--------|------|")
    for name in sorted(sys.builtin_module_names)[:5]:
        print(f"| `{name}` | built-in |")

Renders as a real HTML <table> (output truncated to 5 entries):

Module

Type

_abc

built-in

_ast

built-in

_bisect

built-in

_blake2

built-in

_codecs

built-in

Self-updating source with :mirror:

python:render accepts a :mirror: flag. On top of rendering live, a mirror block keeps a copy of its generated Markdown in the source .md, between two HTML-comment markers directly below the fence. The output stays reviewable in the raw file, in diffs, and on GitHub, which renders the mirrored Markdown even though it never executes the block. It is the marker region of a docs_update.py script, with the generator inlined into the page: no separate regenerator script, and no drift.

Add :mirror: to a python:render fence:

```{python:render}
:mirror:
from click_extra.table import TableFormat, render_table

print(render_table(
    [["Lisbon", "12:00"], ["Denver", "05:00"]],
    headers=["City", "Local time"],
    table_format=TableFormat.GITHUB,
))
```

Running click-extra refresh-directives on the file inserts the mirrored region below the fence, and refreshes it in place on every later run:

```{python:render}
:mirror:
...
```

<!-- mirror -->

| City   | Local time |
| :----- | :--------- |
| Lisbon | 12:00      |
| Denver | 05:00      |

<!-- mirror-end -->

A few properties follow from the mirror being real Markdown:

  • The mirrored region is the single rendered copy, so the directive emits nothing of its own in mirror mode: otherwise the table would render twice. Add :show-source: to also show the Python block above the region.

  • Sphinx builds regenerate the region in memory before parsing the page, so the rendered HTML is always fresh, even when the committed region is stale. The build never writes to the source file: the committed copy is refreshed by click-extra refresh-directives, typically from the same automation that keeps {matrix} blocks current.

  • The <!-- mirror --> … <!-- mirror-end --> pair follows the same marker grammar as the <!-- matrix … --> regions, and a mirror example nested inside a longer code fence (like the ones on this page) is never executed or refreshed.

  • The region is reformatted by mdformat like any other Markdown, so a mirror block must print mdformat-canonical Markdown. render_table in GITHUB mode already does; a hand-built table may be re-aligned by the formatter and then fight the generator.

:mirror: is scoped to python:render in a Markdown host, and shares the click_extra_enable_exec_directives opt-in with the rest of the executing directives.

Hiding the generator with <!-- mirror-src -->

A :mirror: fence renders live and mirrors its output into the source, but the generator fence itself stays visible: on GitHub or PyPI, which show the raw Markdown without running Sphinx, the reader sees the python:render code block above the table. When the output is the whole point (a table or diagram in readme.md) and the generator is just plumbing, the <!-- mirror-src --> comment form moves the generator into an HTML comment, so only its output renders.

The generator Python lives between an opening <!-- mirror-src line and a closing -->, each on its own line:

<!-- mirror-src
from click_extra.table import TableFormat, render_table

print(render_table(
    [["Lisbon", "12:00"], ["Denver", "05:00"]],
    headers=["City", "Local time"],
    table_format=TableFormat.GITHUB,
))
-->

Running click-extra refresh-directives executes the generator and writes its output just below the comment, closed by a <!-- mirror-src-end --> marker:

<!-- mirror-src
...
-->

| City   | Local time |
| :----- | :--------- |
| Lisbon | 12:00      |
| Denver | 05:00      |

<!-- mirror-src-end -->

Both markers are HTML comments, so GitHub, PyPI, and any plain Markdown renderer show only the generated table while the generator stays out of sight. Everything else matches the :mirror: fence: Sphinx regenerates the region in memory on each build so the rendered HTML is never stale, the committed copy is refreshed offline by click-extra refresh-directives, the region is reformatted by mdformat (so the generator must print mdformat-canonical Markdown), and an example nested inside a longer code fence (like the two above) is copied verbatim, never executed.

Choose between the two forms by what should be on the page: the :mirror: fence when the generator belongs there, like a docs example teaching python:render itself; the <!-- mirror-src --> comment when the page should read as its output alone, like a readme.md rendered on PyPI.

Cross-format rendering

python:render-myst and python:render-rst let a host file embed content authored in the other markup. This page is MyST, but the following block prints reST and parses it as such:

Note

A persimmon must be very ripe to eat raw.

In an rST host, python:render-myst provides the symmetric path: print MyST and have it parsed as MyST regardless of the surrounding .rst file.

Namespace persistence

Like click:source / click:run, the Python runner holds a per-document namespace, so consecutive blocks share imports and variables:

from textwrap import dedent

GREETING = "hello, sphinx"
HELLO, SPHINX

The python:source block ran silently to seed dedent and GREETING; the subsequent python:run referenced both.

Shared options

python:run and the python:render* directives accept the same option spec as click:run. Defaults match: results shown, source hidden, so an inline import line in a python:run block runs silently and stays out of the rendered output.

Option

Effect

Default

:show-source: / :hide-source:

Render the directive’s source block, or omit it.

hidden

:show-results: / :hide-results:

Render the captured output block, or omit it.

shown

:mirror:

Keep a refreshable copy of the generated Markdown below the fence (python:render only).

off

:linenos:

Display line numbers in both blocks.

off

:lineno-start:

Starting line number when :linenos: is on. Applies to source.

1

:emphasize-lines:

Highlight lines in the source block. Syntax: 1,3-5.

none

:emphasize-result-lines:

Highlight lines in the result block. Same syntax as :emphasize-lines:.

none

:language:

Override the Pygments lexer used to render the result block.

text

:caption:

Set a caption on the rendered code block.

none

:name:

Anchor name for cross-referencing.

none

:class:

Extra CSS class on the rendered block.

none

:dedent:

Strip N leading spaces from every line of the source.

0

:force:

Suppress minor highlighting errors.

off

See also

Some related projects for build-time Python execution:

  • sphinx-exec-code: single exec_code directive; supports external :filename: and inline #hide: / #skip: markers; fresh interpreter per block.

  • jupyter-sphinx: runs Python in a real Jupyter kernel; rich outputs (matplotlib, widgets).

  • MyST-NB: executes .ipynb and code-cell .md; glue / eval roles inject computed values into prose.

  • sphinx-jinja: Jinja2 templates with Python context, output parsed as reST/MyST. Closest analogue for the docs-as-code pattern without exec.

The matrix directive

The matrix directive renders a package’s release compatibility matrix for a given axis. Unlike the click:* and python:* families, it runs a fixed generator rather than user-supplied Python, so it carries no execution surface and is registered without the click_extra_enable_exec_directives opt-in. Two axes are built in:

  • {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).

Both trim their table to the support envelope of the project, which can leave out the oldest release ranges, then the oldest versions that no remaining range supports.

The generated table lives in the source, kept current by the offline updater described below, so it shows up in the raw Markdown (and in pull-request diffs) and the HTML build needs no git access (it works on a shallow clone). There are two ways to write it, both refreshed by the same refresh-directives command:

  • A directive fence, ```{matrix} python … ```, rendered by Sphinx. Simplest on a docs-only page, but GitHub shows the fenced block as a code block. An empty fence falls back to generating from the git tags at build time, so a freshly authored block renders before its first refresh.

  • A comment marker region, <!-- matrix python --> … <!-- matrix-end -->, with the raw table between the markers. Being plain Markdown, it renders as a real table on GitHub and PyPI as well as in Sphinx. Options go in the start comment as key=value pairs and bare flags: <!-- matrix click show-spec -->. install.md’s tables use this form so they render everywhere.

The examples below use the directive fence; the marker form takes the same axis and options.

The python axis

This project uses it for the Python compatibility table in install.md. You write the block with just its axis and options:

```{matrix} python
:package: click-extra
```

and the updater fills in the table below the options, regenerated from every vMAJOR.MINOR.PATCH tag (reading the declared Python support from the Programming Language :: Python :: X.Y classifiers in pyproject.toml, falling back to requires-python, Poetry’s python = "...", then setup.py’s python_requires). Consecutive releases that agree are grouped into one row, labeled by minor series (4.9.x → 4.10.x) unless a series is split across two rows, where the split bound shows its exact version (5.0.x → 6.0.0, then 6.0.1 → 6.1.x). :show-date: follows the lower bound with the date of the range’s first release, like 6.0.x (2025-09-25) → 9.x. A floor-only declaration is capped at the latest Python released while the range was current. The top-left cell names both axes, as corner_header() spells them:

```{matrix} python
:package: click-extra

| `click-extra` ↴ \\ Python → | `3.15` | `3.14` | `3.13` | `3.12` | `3.11` | `3.10` | `3.9` | `3.8` | `3.7` |
| :-------------------------- | :----: | :----: | :----: | :----: | :----: | :----: | :---: | :---: | :---: |
| `10.x`                      |   ✅   |   ✅   |   ✅   |   ✅   |   ✅   |   ❌   |  ❌   |  ❌   |  ❌   |
| `9.3.2` → `9.5.x`           |   ✅   |   ✅   |   ✅   |   ✅   |   ✅   |   ✅   |  ❌   |  ❌   |  ❌   |
| `6.2.x` → `9.3.1`           |   –    |   ✅   |   ✅   |   ✅   |   ✅   |   ✅   |  ❌   |  ❌   |  ❌   |
| `6.0.1` → `6.1.x`           |   –    |   ✅   |   ✅   |   ✅   |   ✅   |   ❌   |  ❌   |  ❌   |  ❌   |
| `5.0.x` → `6.0.0`           |   –    |   –    |   ✅   |   ✅   |   ✅   |   ❌   |  ❌   |  ❌   |  ❌   |
| `4.11.x` → `4.15.x`         |   –    |   –    |   ✅   |   ✅   |   ✅   |   ✅   |  ❌   |  ❌   |  ❌   |
| `4.9.x` → `4.10.x`          |   –    |   –    |   –    |   ✅   |   ✅   |   ✅   |  ✅   |  ❌   |  ❌   |
| `4.0.x` → `4.8.x`           |   –    |   –    |   –    |   ✅   |   ✅   |   ✅   |  ✅   |  ✅   |  ❌   |
| `0.0.x` → `3.10.x`          |   –    |   –    |   –    |   –    |   ✅   |   ✅   |  ✅   |  ✅   |  ✅   |
```

Three states, two sources

A release declares its Python support twice, and the two declarations answer different questions. The classifier list is what the project claims to have tested. requires-python is what an installer enforces: fall outside it and pip refuses to install, whatever the classifiers say. The matrix keeps them apart:

Cell

Meaning

✅

Declared, via a Programming Language :: Python :: X.Y classifier.

❌

Ruled out by requires-python: below its floor, on or above its ceiling, or excluded by a != clause.

–

Neither. The release never claimed that version, and nothing in its metadata stops you.

The third state is what a two-state table has to lie about. When 4.9.0 shipped in July 2024 it declared requires-python = ">= 3.9" with classifiers up to 3.12, and Python 3.13 did not exist yet. Marking that cell ❌ would assert an incompatibility nobody ever declared, so it renders – instead, while 3.8 stays ❌ because the >= 3.9 floor genuinely rules it out.

The result reads as a staircase: ❌ fills the lower-left as the floor rises over the years, ✅ the middle band, and – the upper-right where the future had not happened yet.

A dependency axis

{matrix} <distribution> tracks a runtime dependency instead. For each release range it reads that distribution’s requirement specifier (PEP 621, Poetry, or setup.py) and marks ✅ / ❌ for each column version with packaging. An extras bracket and an environment marker are both transparent: tabulate[widechars]>=0.9 and tomli>=2; python_version<'3.11' each track the plain >= range. The distribution is matched on its PEP 503 normalized name, looked up in the runtime dependencies then in those behind an extra. Development dependency groups (PEP 735) are skipped, since no installer resolves them for a consumer. Columns are auto-derived from the distribution’s stable releases on PyPI, plus the version resolved in uv.lock unless it is a pre-release or a development version: consecutive releases that every range in the table treats alike share one column. A range therefore holds the same cell for every release of a column. Columns are labeled like the rows, but read from their newest bound while they run newest first, so the versions decrease from left to right across the header row: 3.0.4 ← 3.0.1, 2.1.x, 1.x. The oldest releases that no range in the table accepts get no column. The PyPI lookup applies no cooldown, since an installer applies none either, so a new release shows up as soon as it is published. It needs network access: when PyPI cannot answer, the refresh logs a warning and leaves the block as it was, so an outage never rewrites a good table. An empty fence has no table to keep, so its build-time rendering bins the floors of the ranges instead, which gives a coarser table. Add :show-spec: for a Spec column with each range’s raw specifier, in the release’s own spelling. Without it, consecutive ranges merge whenever their cells match, since they then accept the same releases. With it, they merge only when their specifiers are equivalent, because a merged row shows a single one.

Cells are three-valued here too, and the dates of the releases decide the third state:

Cell

Meaning

✅

The specifier accepts the release, which came out while the range was the latest one, in a major out by its last release.

❌

The specifier rules the release out.

–

The specifier accepts the release, but it came out after the next range replaced this one, or in a major out after the last release of this range.

An open specifier like click>=8.0 lets every future Click through, whether it works or not, and – stops the table from reading that as support. A range is the latest one from its first release until the first release of the next range. A dependency release out on that last day counts as ✅. A replaced range also never met a major that came out after its own last release, even before the next range: it reads – there, since a new major is free to break. The latest range carries no such cap. A release date is the day the first of its installable files reached PyPI, in UTC. Ranges are compared parsed, so a re-spelled specifier continues its range: cloup >= 3.0.7 rewritten as cloup>=3.0.7 by a formatter starts no new range, and cuts no range short.

Poetry’s own range syntax is translated to PEP 440 before evaluation, since a project’s older tags usually predate its move to PEP 621. Carets follow Poetry’s rule of bumping the leftmost non-zero component, so ^1.2.3 caps at 2.0.0 while ^0.2.3 caps at 0.3.0 and ^0.0.3 at 0.0.4: under a 0. prefix every release may break, and a caret there covers far less than the major series. Tilde and wildcard ranges (~1, ~1.2, 1.*, 1.2.*) translate the same way. A pre-, post- or dev-release suffix stays on the floor and leaves the ceiling alone, so ^2.0.0.post1 becomes >=2.0.0.post1,<3.0.0.

This project uses it for the Click and Cloup compatibility tables. The Click one reads:

```{matrix} click
:package: click-extra

| `click-extra` ↴ \\ `click` → | `8.5.1` | `8.5.0` | `8.4.2` ← `8.4.1` | `8.4.0` ← `8.3.1` |
| :--------------------------- | :-----: | :-----: | :---------------: | :---------------: |
| `10.x`                       |   ✅    |   ✅    |        ❌         |        ❌         |
| `9.x`                        |    –    |   ✅    |        ✅         |        ❌         |
| `8.x`                        |    –    |   ✅    |        ✅         |        ✅         |
```

The support envelope

Both axes keep only the support envelope of the project: the releases and versions still in scope. The table itself defines it:

  1. Its floor is the oldest version the latest release range supports, like Python 3.11 for click-extra.

  2. Its rows run from the latest range down to the oldest one that supports the floor or a later version. The ranges in between stay, whatever they hold, so a release that dropped a version for a while keeps its row.

  3. Its columns start at the oldest version a kept range supports. A later column stays even when no kept range supports it, so a gap in support stays visible.

As the floor moves up, the oldest rows drop off, then the oldest columns that no remaining row supports. A version the latest range no longer supports can thus keep its column: the Python table of click-extra still shows 3.7 to 3.10, which its 10.x row marks ❌. A latest range that supports nothing, like one pinning a yanked release, sets no floor, and the table keeps every row.

Add :full-history: to keep every release range instead.

On the python axis, :python-floor: drops its columns first, so a value above the oldest Python of the latest range raises the floor too. Under :full-history:, it drops columns only.

In an HTML build, the extension tints each cell of a two-axis table that holds a state alone: green for ✅, red for ❌ and grey for –. The tints are translucent, so they work on light and dark themes alike.

The envelope region

The <!-- envelope --> region lists the obsolete bounds of the support envelope, like for a support policy. Its start marker names the axes it covers, and takes the package, path and tag-pattern options of a matrix marker:

<!-- envelope python click cloup -->
<!-- envelope-end -->

The refresh fills it with one item per bound. For click-extra, it reads:

<!-- envelope python click cloup -->

- `click-extra` releases before `8.0.0` (2026-06-22)
- Python versions before `3.10` (2021-10-04)
- `click` versions before `8.3.1` (2025-11-15)
- `cloup` versions before `3.0.7` (2025-03-15)

<!-- envelope-end -->

Each axis keeps its own envelope, as its matrix does. A release is in scope only when every envelope that leaves out releases keeps it, so the release bound is the newest of their first releases. Each version bound is then the oldest version that a release in scope supports. It can be newer than the oldest column of the axis’ matrix: click-extra releases from 8.0.0 onward support no Python before 3.10, while its Python table goes down to 3.7. Each bound carries its release date: the date of the tag for a release, the date of its final release for a Python, and the PyPI date for a dependency release.

The region has no directive form: its list renders as is, on GitHub and in Sphinx alike.

Options

Option

Effect

Default

:package:

Header column label, rendered in backticks.

declared project name

:path:

Git working tree to walk, absolute or relative to the documented project’s root.

project’s git root

:version-floor:

Drop release rows below this package version.

none (all tags)

:tag-pattern:

Regex selecting release tags.

^v\d+\.\d+\.\d+$

:column-order:

Left-to-right ordering of the version columns: newest-first or oldest-first.

newest-first

:row-order:

Top-to-bottom ordering of the release rows: newest-first or oldest-first.

newest-first

:python-floor:

(python axis) Drop Python X.Y columns below this version.

none (all columns)

:show-spec:

(dependency axis) Add a Spec column with each range’s raw specifier.

off

:show-date:

Follow each row label with the release date of its first tag.

off

:full-history:

Keep every release range, not just the support envelope.

off

The label defaults to the name the project declares in its pyproject.toml: the [project] table is read first, then Poetry’s [tool.poetry]. A clone, a fork or a git worktree under another folder name then renders the same table. A project that declares no name is labeled with the name of its folder.

The :path: option makes the directive reusable across repositories: point it at a sibling checkout to render another package’s matrix.

Keeping the tables current

The embedded tables are refreshed offline, formatter-style, by the refresh-directives command (which needs the sphinx extra):

$ click-extra refresh-directives docs/

It walks the given Markdown files or directories, regenerates each matrix block’s table (both the {matrix} directive fences and the <!-- matrix … --> marker regions) from that block’s axis, options, and the project’s git tags, and rewrites the block in place. Each <!-- envelope … --> region gets its list of bounds regenerated the same way. Pass --check to write nothing and exit non-zero when a block is stale, so a CI job or pre-commit hook can fail on an out-of-date matrix. The same logic is importable as click_extra.sphinx.matrix.update_matrix_blocks(paths, check=...). A block whose generation fails (missing git binary, non-repository :path:, no matching data, or a PyPI lookup that cannot answer for a dependency axis) is left untouched, so a transient failure never wipes a good table, and --check reports no drift for it. Examples nested inside longer code fences (like the ones on this page) are documented illustrations and are never refreshed.

The same command also refreshes the python:render :mirror: regions found in the same files, in both the visible fence and the invisible <!-- mirror-src --> comment forms, by executing each block’s Python (click_extra.sphinx.python.update_mirror_blocks(paths, check=...) is the importable form). One invocation therefore keeps every self-updating block of a documentation tree current, whatever its kind.

Note

Only the updater (and the empty-block fallback) needs the release tags, since it is the part that shells out to git. Run it wherever the full tag history is available. The HTML build renders the embedded table verbatim and needs no git access, so shallow clones and read-only build hosts render the matrix fine.

For content a directive cannot produce on its own, like a shared registry dumped into several files or an external generator’s output, the same marker machinery is exposed as three primitives, importable from click_extra.markdown.blocks without the sphinx extra:

  • marker_res(name) builds the (open, close) regexes of a <!-- name … --> / <!-- name-end --> region, the grammar every self-updating marker shares.

  • replace_region(text, name, content) swaps the body between those markers for content, keeping the markers so the region round-trips. It returns the text unchanged when either marker is absent, so it is safe to fan out over files that do not all carry the region.

  • update_blocks(paths, rewrite, check=...) applies a rewrite(text, path) callback to every Markdown file under paths, writing back only the ones it changed (or, under check, returning the ones it would change). It is the read-rewrite-report loop behind both update_matrix_blocks and update_mirror_blocks.

replace_region is the counterpart to those two refreshers for content that originates outside the document rather than from an inline directive.