公用程序

Sphinx提供实用程序类和函数来开发插件。

组件的基类

这些基类有助于插件轻松获取Sphinx组件（例如：class:.Config，：class:`.BuildEnvironment`等等）。

备注

它们的子类可能无法与裸docutil一起工作，因为它们与Sphinx强耦合。

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

变换的基类。

与``docutils.transforms.Transform``相比，该类改进了Sphinx接口的可访问性。

property app: Sphinx

对：class:`.Sphinx`对象的引用。

property config: Config

对：class:`.Config`对象的引用。

property env: BuildEnvironment

对：类：`.BuildEnvironment`对象的引用。

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

后转换的基类。

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

重写以将转换应用于文档树。

is_supported() → bool

检查此转换是否适用于当前生成器。

run(**kwargs: Any) → None

Main method of post transforms.

子类应该重写此方法，而不是“apply（）”。

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

Sphinx指令的基类。

这个类为Sphinx指令提供了助手方法。

备注

此类的子类可能无法与docutils一起使用。这个类与Sphinx紧密耦合。

get_location() → str

Get current location info for logging.

get_source_info() → tuple[str, int]

获取源和行号。

set_source_info(node: Node) → None

为节点设置源和行号。

property config: Config

对：class:`.Config`对象的引用。

property env: BuildEnvironment

对：类：`.BuildEnvironment`对象的引用。

class sphinx.util.docutils.SphinxRole

sphinx角色的基类。

此类为Sphinx角色提供帮助程序方法。

备注

此类的子类可能无法与docutils一起使用。这个类与Sphinx紧密耦合。

get_location() → str

Get current location info for logging.

property config: Config

对：class:`.Config`对象的引用。

content: Sequence[str]

A list of strings, the directive content for customisation (from the “role” directive).

property env: BuildEnvironment

对：类：`.BuildEnvironment`对象的引用。

inliner: Inliner

在``docutils.parsers.rst.状态。内联线``对象。

lineno: int

解释文本开始的行号。

name: str

文档中实际使用的角色名称。

options: dict[str, Any]

A dictionary of directive options for customisation (from the “role” directive).

rawtext: str

包含整个解释文本输入的字符串。

text: str

解释文本内容。

class sphinx.util.docutils.ReferenceRole

引用角色的基类。

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 to self.title and self.target.

disabled: bool

布尔值表示引用被禁用。

has_explicit_title: bool

布尔值表示角色是否具有显式标题。

target: str

解释文本的链接目标。

title: str

解释文本的链接标题。

class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)

图像转换器的基类。

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.

制作自定义图像转换器有三个步骤：

1. 生成“ImageConverter”类的子类

2. 重写“转换规则”、“is_available（）”和“convert（）``

3. 使用：py:meth:将图像转换器注册到Sphinx。Sphinx.add_post_转换

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

返回图像转换器是否可用。

available: bool | None = None

转换器是否可用。将在构建的第一次调用时被填充。 其结果在同一过程中共享。

待处理

这应该被重构，不要在没有类变量的情况下存储状态。

conversion_rules: list[tuple[str, str]] = []

图像转换器支持的转换规则。它表示为源图像格式（mimetype）和目标图像格式对的列表：

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).

公用程序组件

class sphinx.events.EventManager(app: Sphinx)

Sphinx的活动管理器

add(name: str) → None

注册自定义Sphinx事件。

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

将处理程序连接到特定事件。

disconnect(listener_id: int) → None

断开处理程序。

emit(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list

发射Sphinx事件。

emit_firstresult(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any

发出Sphinx事件并返回第一个结果。

这将返回第一个不返回“None”的处理程序的结果。

Utility types

class sphinx.util.typing.ExtensionMetadata

The metadata returned by an extension’s setup() function.

See 扩展元数据.

env_version: int

An integer that identifies the version of env data added by the extension.

parallel_read_safe: bool

Indicate whether parallel reading of source files is supported by the extension.

parallel_write_safe: bool

Indicate whether parallel writing of output files is supported by the extension (default: True).

version: str

The extension version (default: 'unknown version').