`papyri.directives:make_include_handler`

source: /papyri/directives.py:835

Signature

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

Summary

Return an .. include:: directive handler bound to the given path context.

Extended Summary

The returned callable has the standard (argument, options, content) handler signature. It resolves the included file relative to doc_path (for relative paths) or doc_root (for /-prefixed Sphinx-absolute paths), reads it as RST, and returns the parsed IR nodes inline.

Supported options:

:start-line: — first line to include (0-based, inclusive; negative values count from the end).
:end-line: — line at which to stop (0-based, exclusive; negative values count from the end).
:start-after: — skip everything up to and including the first occurrence of this text.
:end-after: — stop after the first occurrence of this text (the matching text itself is included in the output).

When the file cannot be found, or when the required path context is absent, a warning is logged and an empty list is returned.

Aliases

papyri.directives.make_include_handler