Utilities

Utilities

Sphinx provides utility classes and functions to develop extensions.

Base classes for components

These base classes are useful to allow your extensions to obtain Sphinx components (e.g. Config, BuildEnvironment and so on) easily.

Note

The subclasses of them might not work with bare docutils because they are strongly coupled with Sphinx.

class sphinx.transforms.SphinxTransform(document, startnode=None)[source]

A base class of Transforms.

Compared with docutils.transforms.Transform, this class improves accessibility to Sphinx APIs.

property app: Sphinx

Reference to the Sphinx object.

property config: sphinx.config.Config

Reference to the Config object.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)[source]

A base class of post-transforms.

Post transforms are invoked to modify the document to restructure it for outputting. They do resolving references, convert images, special transformation for each output formats and so on. This class helps to implement these post transforms.

apply(**kwargs: Any) → None[source]

Override to apply the transform to the document tree.

is_supported() → bool[source]

Check this transform working for current builder.

run(**kwargs: Any) → None[source]

main method of post transforms.

Subclasses should override this method instead of apply().

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

A base class for Sphinx directives.

This class provides helper methods for Sphinx directives.

Note

The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx.

get_source_info() → Tuple[str, int][source]

Get source and line number.

set_source_info(node: docutils.nodes.Node) → None[source]

Set source and line number to the node.

property config: Config

Reference to the Config object.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

class sphinx.util.docutils.SphinxRole[source]

A base class for Sphinx roles.

This class provides helper methods for Sphinx roles.

Note

The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx.

property config: Config

Reference to the Config object.

content: List[str]

A list of strings, the directive content for customization

property env: BuildEnvironment

Reference to the BuildEnvironment object.

inliner: docutils.parsers.rst.states.Inliner

The docutils.parsers.rst.states.Inliner object.

lineno: int

The line number where the interpreted text begins.

name: str

The role name actually used in the document.

options: Dict

A dictionary of directive options for customization

rawtext: str

A string containing the entire interpreted text input.

text: str

The interpreted text content.

class sphinx.util.docutils.ReferenceRole[source]

A base class for reference roles.

The reference roles can accpet link title style as a text for the role. The parsed result; link title and target will be stored to self.title and self.target.

disabled: bool

A boolean indicates the reference is disabled.

has_explicit_title: bool

A boolean indicates the role has explicit title or not.

target: str

The link target for the interpreted text.

title: str

The link title for the interpreted text.

class sphinx.transforms.post_transforms.images.ImageConverter(*args: Any, **kwargs: Any)[source]

A base class for image converters.

An image converter is kind of Docutils transform module. It is used to convert image files which does not supported by builder to appropriate format for that builder.

For example, LaTeX builder supports PDF, PNG and JPEG as image formats. However it does not support SVG images. For such case, to use image converters allows to embed these unsupported images into the document. One of image converters; sphinx.ext.imgconverter can convert a SVG image to PNG format using Imagemagick internally.

There are three steps to make your custom image converter:

1. Make a subclass of ImageConverter class

2. Override conversion_rules, is_available() and convert()

3. Register your image converter to Sphinx using Sphinx.add_post_transform()

convert(_from: str, _to: str) → bool[source]

Convert a image file to expected format.

_from is a path for source image file, and _to is a path for destination file.

is_available() → bool[source]

Return the image converter is available or not.

available: Optional[bool] = None

The converter is available or not. Will be filled at the first call of the build. The result is shared in the same process.

Todo

This should be refactored not to store the state without class variable.

conversion_rules: List[Tuple[str, str]] = []

A conversion rules the image converter supports. It is represented as a list of pair of source image format (mimetype) and destination one:

conversion_rules = [
    ('image/svg+xml', 'image/png'),
    ('image/gif', 'image/png'),
    ('application/pdf', 'image/png'),
]

Utility components

class sphinx.events.EventManager(app: Sphinx)[source]

Event manager for Sphinx.

add(name: str) → None[source]

Register a custom Sphinx event.

connect(name: str, callback: Callable, priority: int) → int[source]

Connect a handler to specific event.

disconnect(listener_id: int) → None[source]

Disconnect a handler.

emit(name: str, *args: Any, allowed_exceptions: Tuple[Type[Exception], ...] = ()) → List[source]

Emit a Sphinx event.

emit_firstresult(name: str, *args: Any, allowed_exceptions: Tuple[Type[Exception], ...] = ()) → Any[source]

Emit a Sphinx event and returns first result.

This returns the result of the first handler that doesn’t return None.