photon_platform.publish.images.directive

Directives for image processing.

Classes

picture_node	Custom node for containing responsive picture elements.
PictureDirective	Directive for inserting responsive pictures and interactive SVG figures.

Functions

prepare_inline_svg(svg_path[, as_thumbnail]) → str | None	Read an SVG file and prepare it for inline HTML rendering controlled by global CSS.
visit_picture_node(self, node) → None	HTML visitor for picture_node.
depart_picture_node(self, node) → None	Departure visitor for picture_node.
register_standalone_picture() → None	Register picture directive and HTML visitors with standalone Docutils.

Module Contents

photon_platform.publish.images.directive.prepare_inline_svg(svg_path: pathlib.Path | str, as_thumbnail: bool = False) → str | None

Read an SVG file and prepare it for inline HTML rendering controlled by global CSS.

Strips XML/DOCTYPE headers, embedded <style> blocks, and hardcoded background <rect> elements so theme CSS variables (–geom-fg, –geom-bg, etc.) govern light/dark mode. When as_thumbnail is True, also strips hidden highlight overlays and element IDs to avoid duplicate DOM IDs on collection index pages.

class photon_platform.publish.images.directive.picture_node(rawsource: str = '', *children, **attributes: Any)

Bases: docutils.nodes.General, docutils.nodes.Element

Custom node for containing responsive picture elements.

photon_platform.publish.images.directive.visit_picture_node(self: Any, node: docutils.nodes.Element) → None

HTML visitor for picture_node.

Renders a standard <figure> with nested <picture> element for raster images, or a clean <figure class=”photon-picture photon-svg”><img …/></figure> for SVGs and standalone Docutils rendering.

Parameters:

• self – The translator instance.

• node – The picture_node being visited.

photon_platform.publish.images.directive.depart_picture_node(self: Any, node: docutils.nodes.Element) → None

Departure visitor for picture_node.

Parameters:

• self – The translator instance.

• node – The picture_node being visited.

class photon_platform.publish.images.directive.PictureDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

Directive for inserting responsive pictures and interactive SVG figures.

required_arguments = 1

Number of required directive arguments.

optional_arguments = 0

Number of optional arguments after the required arguments.

final_argument_whitespace = True

May the final argument contain whitespace?

option_spec

Mapping of option names to validator functions.

property env: Any

Return the Sphinx BuildEnvironment if running inside Sphinx, else None.

run() → List[docutils.nodes.Node]

Process the picture directive in either Sphinx or standalone Docutils mode.

Returns:

A list containing the picture_node.

photon_platform.publish.images.directive.register_standalone_picture() → None

Register picture directive and HTML visitors with standalone Docutils.