实用程序

Sphinx 提供了用于开发扩展的实用程序类和函数。

组件基类

这些基类有助于使您的扩展能够轻松地获取 Sphinx 组件（例如 Config、BuildEnvironment 等）。

注意

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

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

转换的基类。

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

后置转换的基类。

后置转换用于修改文档以重构其输出结构。它们解析引用、转换图像、对每种输出格式进行特殊转换等等。此类有助于实现这些后置转换。

apply(**kwargs: Any) → None

覆盖以将转换应用于文档树。

is_supported() → bool

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

run(**kwargs: Any) → None

后置转换的主要方法。

子类应该覆盖此方法而不是 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 – 解释文本开始的行号。

返回值:

节点列表（文本和内联元素）以及系统消息列表。

版本 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 转换模块。它用于将构建器不支持的图像文件转换为该构建器适用的格式。

例如，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, _to: str) → bool

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

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

is_available() → bool

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

available: bool | None = None

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

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

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

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, list[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: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], Sequence[str]], None], 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

发出 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

一个整数，用于标识扩展添加的 env 数据的版本。

parallel_read_safe: bool

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

parallel_write_safe: bool

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

version: str

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

上一页

i18n API

下一页

测试 API