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.
Белешка
The subclasses of them might not work with bare docutils because they are strongly coupled with Sphinx.
- class sphinx.transforms.SphinxTransform(document, startnode=None)[изворни код]¶
A base class of Transforms.
Compared with
docutils.transforms.Transform
, this class improves accessibility to Sphinx APIs.- property env: BuildEnvironment¶
Reference to the
BuildEnvironment
object.
- class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)[изворни код]¶
A base class of post-transforms.
Post transforms are invoked to modify the document to restructure it for outputting. They resolve references, convert images, do special transformation for each output formats and so on. This class helps to implement these post transforms.
- apply(**kwargs: Any) None [изворни код]¶
Override to apply the transform to the document tree.
- is_supported() bool [изворни код]¶
Check this transform working for current builder.
- run(**kwargs: Any) None [изворни код]¶
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)[изворни код]¶
A base class for Sphinx directives.
This class provides helper methods for Sphinx directives.
Белешка
The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx.
- get_location() str [изворни код]¶
Get current location info for logging.
- get_source_info() tuple[str, int] [изворни код]¶
Get source and line number.
- set_source_info(node: Node) None [изворни код]¶
Set source and line number to the node.
- property env: BuildEnvironment¶
Reference to the
BuildEnvironment
object.
- class sphinx.util.docutils.SphinxRole[изворни код]¶
A base class for Sphinx roles.
This class provides helper methods for Sphinx roles.
Белешка
The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx.
- get_location() str [изворни код]¶
Get current location info for logging.
- content: Sequence[str]¶
A list of strings, the directive content for customisation (from the „role” directive).
- property env: BuildEnvironment¶
Reference to the
BuildEnvironment
object.
- inliner: Inliner¶
The
docutils.parsers.rst.states.Inliner
object.
- class sphinx.util.docutils.ReferenceRole[изворни код]¶
A base class for reference roles.
The reference roles can accept
link title <target>
style as a text for the role. The parsed result; link title and target will be stored toself.title
andself.target
.
- class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)[изворни код]¶
A base class for image converters.
An image converter is kind of Docutils transform module. It is used to convert image files which are not supported by a builder to the 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, using image converters allows to embed these unsupported images into the document. One of the 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:
Make a subclass of
ImageConverter
classOverride
conversion_rules
,is_available()
andconvert()
Register your image converter to Sphinx using
Sphinx.add_post_transform()
- convert(_from: str, _to: str) bool [изворни код]¶
Convert an image file to the expected format.
_from is a path of the source image file, and _to is a path of the destination file.
- is_available() bool [изворни код]¶
Return the image converter is available or not.
- available: bool | None = 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.
План
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'), ]
- default_priority = 200¶
Numerical priority of this transform, 0 through 999 (override).
Utility components¶
- class sphinx.events.EventManager(app: Sphinx)[изворни код]¶
Event manager for Sphinx.
- add(name: str) None [изворни код]¶
Register a custom Sphinx event.
- connect(name: str, callback: Callable, priority: int) int [изворни код]¶
Connect a handler to specific event.
- disconnect(listener_id: int) None [изворни код]¶
Disconnect a handler.
Utility types¶
- class sphinx.util.typing.ExtensionMetadata[изворни код]¶
The metadata returned by an extension’s
setup()
function.See Extension metadata.
- parallel_read_safe: bool¶
Indicate whether parallel reading of source files is supported by the extension.