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
env
¶ Reference to the
BuildEnvironment
object.
-
property
-
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.
-
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.
-
property
env
¶ Reference to the
BuildEnvironment
object.
-
property
-
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.
-
content
= None¶ A list of strings, the directive content for customization
-
property
env
¶ Reference to the
BuildEnvironment
object.
-
inliner
= None¶ The
docutils.parsers.rst.states.Inliner
object.
-
lineno
= None¶ The line number where the interpreted text begins.
-
name
= None¶ The role name actually used in the document.
-
options
= None¶ A dictionary of directive options for customization
-
rawtext
= None¶ A string containing the entire interpreted text input.
-
text
= None¶ The interpreted text content.
-
-
class
sphinx.util.docutils.
ReferenceRole
[source]¶ A base class for reference roles.
The reference roles can accpet
link title <target>
style as a text for the role. The parsed result; link title and target will be stored toself.title
andself.target
.-
has_explicit_title
= None¶ A boolean indicates the role has explicit title or not.
-
target
= None¶ The link target for the interpreted text.
-
title
= None¶ 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:
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[source]¶ Convert a image file to expected format.
_from is a path for source image file, and _to is a path for destination file.
-
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'), ]