`papyri.directives:make_image_handler`

source: /papyri/directives.py:721

Signature

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

Summary

Return an .. image:: directive handler bound to the given asset context.

Extended Summary

The returned callable has the standard (argument, options, content) handler signature and can be registered in DirectiveVisiter._handlers like any other handler.

Path resolution rules:

http:// / https:// URIs → Image node (no download).
Paths starting with / → resolved relative to doc_root (Sphinx absolute-path convention, e.g. /_images/foo.png). Falls back to an Image node with a warning when doc_root is None.
All other paths → resolved relative to doc_path (sibling-relative). Falls back to an Image node with a warning when doc_path is None.

Parameters

doc_path: Directory of the RST or Python source file being processed. Used to resolve relative image paths. None disables local-file embedding for relative paths.
asset_store: Callable (name, data) that stores raw bytes under name in the bundle's assets/ directory. None disables local-file embedding.
module: Root module name for the bundle (used to build the RefInfo).
version: Bundle version string (used to build the RefInfo).
doc_root: Root of the documentation tree. Used to resolve /-prefixed (Sphinx-absolute) paths such as /_images/foo.png. None disables resolution of those paths.

Aliases

papyri.directives.make_image_handler