`papyri.directives:make_plot_handler`

source: /papyri/directives.py:460

Signature

def make_plot_handler(asset_store: Callable[[str, bytes], None] | None, module: str, version: str, execute: bool = False, qa: str = plot, doc_path: Path | None = None, doc_root: Path | None = None, warn: DirectiveWarn = <function _log_warn at 0x0000>) → Callable[[str, dict[str, str], str], list[Any]]

Summary

Return a .. plot:: directive handler bound to the given execution context.

Extended Summary

When execute is True and asset_store is available the code body is run via BlockExecutor (same mechanism as doctest examples in gen.py). Every matplotlib figure open after the run is saved as a bundle asset and appended as a Figure node after the Code node.

When execute is False (or matplotlib / asset_store are absent) the code body is returned as a bare Code node so the example is not lost.

Matching Sphinx's plot directive semantics:

An argument naming an external .py script embeds that file as the code body (/-prefixed paths resolve against doc_root, others against doc_path; the inline body, if any, is the caption — dropped).
A doctest-format body (>>> prompts) is displayed verbatim but has its prompts stripped for execution.
Execution namespace is pre-seeded like matplotlib's default plot_pre_code (import numpy as np, from matplotlib import pyplot as plt).

Aliases

papyri.directives.make_plot_handler