实用工具

Sphinx 提供了实用工具类和函数来开发扩展。

组件的基类

这些基类对于允许你的扩展轻松获取 Sphinx 组件（例如 Config, BuildEnvironment 等等）非常有用。

注意

它们的子类可能无法与裸 docutils 一起使用，因为它们与 Sphinx 紧密耦合。

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

Transforms 的基类。

与 docutils.transforms.Transform 相比，此类提高了对 Sphinx API 的可访问性。

property app: Sphinx

引用 Sphinx 对象。

property config: Config

引用 Config 对象。

property env: BuildEnvironment

引用 BuildEnvironment 对象。

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

后处理 transforms 的基类。

调用后处理 transforms 来修改文档，以重新构建文档以便输出。它们解析引用、转换图像、为每种输出格式执行特殊转换等等。此类有助于实现这些后处理 transforms。

apply(**kwargs: Any) → None

重写以将 transform 应用于文档树。

is_supported() → bool

检查此 transform 是否适用于当前构建器。

run(**kwargs: Any) → None

后处理 transforms 的主要方法。

子类应重写此方法而不是 apply()。

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

Sphinx 指令的基类。

此类为 Sphinx 指令提供辅助方法。

在 1.8 版本中添加。

注意

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

get_location() → str

获取当前位置信息以进行日志记录。

在 4.2 版本中添加。

get_source_info() → tuple[str, int]

获取源文件和行号。

在 3.0 版本中添加。

parse_content_to_nodes(allow_section_headings: bool = False) → list[Node]

将指令的内容解析为节点。

参数:

allow_section_headings – 指令内容中是否允许标题（章节）？ 请注意，此选项绕过了 Docutils 对 doctree 结构的常规检查，滥用此选项可能会导致不连贯的 doctree。 在 Docutils 中，章节节点应仅是 Structural 节点的子节点，其中包括 document、section 和 sidebar 节点。

在 7.4 版本中添加。

parse_inline(text: str, *, lineno: int = -1) → tuple[list[Node], list[system_message]]

将 text 解析为内联元素。

参数:

• text – 要解析的文本，应为单行或段落。 这不能包含任何结构元素（标题、过渡、指令等）。

• lineno – 解释文本开始的行号。

返回:

节点列表（文本和内联元素）和 system_messages 列表。

在 7.4 版本中添加。

parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) → list[Node]

将 text 解析为节点。

参数:

• text – 文本，字符串形式。 也接受 StringList。

• allow_section_headings – text 中是否允许标题（章节）？ 请注意，此选项绕过了 Docutils 对 doctree 结构的常规检查，滥用此选项可能会导致不连贯的 doctree。 在 Docutils 中，章节节点应仅是 Structural 节点的子节点，其中包括 document、section 和 sidebar 节点。

• offset – 内容的偏移量。

在 7.4 版本中添加。

set_source_info(node: Node) → None

将源文件和行号设置到节点。

在 2.1 版本中添加。

property config: Config

引用 Config 对象。

在 1.8 版本中添加。

property env: BuildEnvironment

引用 BuildEnvironment 对象。

在 1.8 版本中添加。

class sphinx.util.docutils.SphinxRole

Sphinx 角色的基类。

此类为 Sphinx 角色提供辅助方法。

在 2.0 版本中添加。

注意

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

get_location() → str

获取当前位置信息以进行日志记录。

在 4.2 版本中添加。

property config: Config

引用 Config 对象。

在 2.0 版本中添加。

content: Sequence[str]

字符串列表，用于自定义的指令内容（来自 “role” 指令）。

property env: BuildEnvironment

引用 BuildEnvironment 对象。

在 2.0 版本中添加。

inliner: Inliner

docutils.parsers.rst.states.Inliner 对象。

lineno: int

解释文本开始的行号。

name: str

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

options: dict[str, Any]

用于自定义的指令选项字典（来自 “role” 指令）。

rawtext: str

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

text: str

解释的文本内容。

class sphinx.util.docutils.ReferenceRole

引用角色的基类。

引用角色可以接受 link title <target> 样式作为角色的文本。解析结果；链接标题和目标将存储到 self.title 和 self.target。

在 2.0 版本中添加。

disabled: bool

一个布尔值，指示引用是否被禁用。

has_explicit_title: bool

一个布尔值，指示角色是否具有显式标题。

target: str

解释文本的链接目标。

title: str

解释文本的链接标题。

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

图像转换器的基类。

图像转换器是一种 Docutils transform 模块。它用于将构建器不支持的图像文件转换为该构建器适当的格式。

例如，LaTeX builder 支持 PDF、PNG 和 JPEG 作为图像格式。但是它不支持 SVG 图像。对于这种情况，使用图像转换器可以将这些不受支持的图像嵌入到文档中。其中一个图像转换器；sphinx.ext.imgconverter 可以使用 Imagemagick 在内部将 SVG 图像转换为 PNG 格式。

制作自定义图像转换器需要三个步骤

1. 制作 ImageConverter 类的子类

2. 重写 conversion_rules、is_available() 和 convert()

3. 使用 Sphinx.add_post_transform() 将你的图像转换器注册到 Sphinx

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

将图像文件转换为预期格式。

_from 是源图像文件的路径，_to 是目标文件的路径。

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

此转换的数值优先级，0 到 999（覆盖）。

实用组件

class sphinx.events.EventManager(app: Sphinx)

Sphinx 的事件管理器。

add(name: str) → None

注册一个自定义的 Sphinx 事件。

connect(name: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int) → int

connect(name: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int) → int

connect(name: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int) → int

connect(name: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int) → int

connect(name: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int) → int

connect(name: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int) → int

connect(name: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int) → int

connect(name: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int) → int

connect(name: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int) → int

connect(name: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int) → int

connect(name: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int) → int

connect(name: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int) → int

connect(name: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int) → int

connect(name: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int) → int

connect(name: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int) → int

connect(name: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int) → int

connect(name: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int) → int

connect(name: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int) → int

connect(name: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int) → int

connect(name: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int) → int

connect(name: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int) → int

connect(name: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int) → int

connect(name: Literal['autodoc-before-process-signature'], callback: Callable[[Sphinx, Any, bool], None], priority: int) → int

connect(name: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | None], tuple[str | None, str | None] | None], priority: int) → int

connect(name: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int) → int

connect(name: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], priority: int) → int

connect(name: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int) → int

connect(name: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int) → int

connect(name: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int) → int

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

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

disconnect(listener_id: int) → None

断开处理程序的连接。

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

发射一个 Sphinx 事件。

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

发射一个 Sphinx 事件并返回首个结果。

这会返回第一个未返回 None 的处理程序的结果。

实用工具函数

sphinx.util.parsing.nested_parse_to_nodes(state: RSTState, text: str | StringList, *, source: str = '<generated text>', offset: int = 0, allow_section_headings: bool = True, keep_title_context: bool = False) → list[Node]

将 text 解析为节点。

参数:

• state – 状态机状态。必须是 RSTState 的子类。

• text – 文本，字符串形式。 也接受 StringList。

• source – 文本的来源，用于创建新的 StringList。

• offset – 内容的偏移量。

• allow_section_headings – text 中是否允许标题（章节）？ 请注意，此选项绕过了 Docutils 对 doctree 结构的常规检查，滥用此选项可能会导致不连贯的 doctree。 在 Docutils 中，章节节点应仅是 Structural 节点的子节点，其中包括 document、section 和 sidebar 节点。

• keep_title_context – 如果为 False（默认值），则content 被解析为好像它是一个独立的文档，这意味着标题装饰（例如下划线）不需要与周围的文档匹配。当解析的内容来自完全不同的上下文（例如，文档字符串）时，这很有用。如果为 True，则标题下划线必须与周围文档中的下划线匹配，否则行为未定义。

在 7.4 版本中添加。

实用工具类型

class sphinx.util.typing.ExtensionMetadata

扩展程序的 setup() 函数返回的元数据。

参见 扩展元数据。

env_version: int

一个整数，用于标识扩展程序添加的环境数据的版本。

parallel_read_safe: bool

指示扩展程序是否支持并行读取源文件。

parallel_write_safe: bool

指示扩展程序是否支持并行写入输出文件（默认值：True）。

version: str

扩展程序版本（默认值：'unknown version'）。

Previous

i18n API

Next

Testing API