实用程序¶
Sphinx 提供了实用类和函数来开发扩展。
组件的基类¶
这些基类对于您的扩展程序轻松获取 Sphinx 组件（例如 Config、BuildEnvironment 等）非常有用。
注意
它们的子类可能无法与裸 Docutils 一起使用，因为它们与 Sphinx 紧密耦合。
- class sphinx.transforms.SphinxTransform(document, startnode=None)[source]¶
Transform 的基类。
与
docutils.transforms.Transform相比，此类别改进了对 Sphinx API 的访问。- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用。
- class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)[source]¶
后置转换的基类。
后置转换用于修改文档以重新组织其输出。它们解析引用、转换图像、针对每种输出格式进行特殊转换等。此类有助于实现这些后置转换。
- class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶
Sphinx 指令的基类。
此类别为 Sphinx 指令提供辅助方法。
版本 1.8 中新增。
注意
此类的子类可能无法与 Docutils 一起使用。此类别与 Sphinx 紧密耦合。
- parse_content_to_nodes(allow_section_headings: bool = False) list[Node][source]¶
将指令内容解析为节点。
- 参数:
allow_section_headings – 指令内容中是否允许标题（节）？请注意，此选项绕过了 Docutils 对文档树结构的常规检查，滥用此选项可能导致文档树不一致。在 Docutils 中，节节点应仅作为
Structural节点的子节点，其中包括document、section和sidebar节点。
版本 7.4 新增。
- parse_inline(text: str, *, lineno: int = -1) tuple[list[Node], list[system_message]][source]¶
将 text 解析为内联元素。
- 参数:
text – 要解析的文本，它应该是一行或一段。这不能包含任何结构元素（标题、过渡、指令等）。
lineno – 解释文本开始的行号。
- 返回:
节点列表（文本和内联元素）和 system_messages 列表。
版本 7.4 新增。
- parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) list[Node][source]¶
将 text 解析为节点。
- 参数:
text – 文本，字符串形式。
StringList也接受。allow_section_headings – text 中是否允许标题（节）？请注意，此选项绕过了 Docutils 对文档树结构的常规检查，滥用此选项可能导致文档树不一致。在 Docutils 中，节节点应仅作为
Structural节点的子节点，其中包括document、section和sidebar节点。offset – 内容的偏移量。
版本 7.4 新增。
- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用。版本 1.8 中新增。
- class sphinx.util.docutils.SphinxRole[source]¶
Sphinx 角色的基类。
此类别为 Sphinx 角色提供辅助方法。
2.0 版本新增。
注意
此类的子类可能无法与 Docutils 一起使用。此类别与 Sphinx 紧密耦合。
- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用。2.0 版本新增。
- inliner: Inliner¶
docutils.parsers.rst.states.Inliner对象。
- class sphinx.util.docutils.ReferenceRole[source]¶
引用角色的基类。
引用角色可以接受
link title <target>样式作为角色的文本。解析结果；链接标题和目标将存储在self.title和self.target中。2.0 版本新增。
- class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)[source]¶
图像转换器的基类。
图像转换器是一种 Docutils 转换模块。它用于将构建器不支持的图像文件转换为该构建器适当的格式。
例如，
LaTeX 构建器支持 PDF、PNG 和 JPEG 作为图像格式。但是它不支持 SVG 图像。对于这种情况，使用图像转换器可以将这些不受支持的图像嵌入到文档中。其中一个图像转换器；sphinx.ext.imgconverter 可以使用 Imagemagick 内部将 SVG 图像转换为 PNG 格式。制作自定义图像转换器有三个步骤
创建
ImageConverter类的子类重写
conversion_rules、is_available()和convert()使用
Sphinx.add_post_transform()向 Sphinx 注册图像转换器
- convert(_from: str | PathLike[str], _to: str | PathLike[str]) bool¶
将图像文件转换为预期格式。
_from 是源图像文件的路径，而 _to 是目标文件的路径。
- 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（覆盖）。
实用函数¶
- 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 对文档树结构的常规检查，滥用此选项可能导致文档树不一致。在 Docutils 中，节节点应仅作为
document或section节点的子节点。keep_title_context –
如果此参数为 False（默认值），则 content 将被解析为独立文档，这意味着标题修饰（例如下划线）不需要与周围文档匹配。这在解析内容来自完全不同的上下文（例如 docstrings）时很有用。如果此参数为 True，则标题下划线必须与周围文档中的下划线匹配，否则行为未定义。
警告：在 Docutils 0.21 之前，具有与当前节级别更高的装饰样式的节会被静默丢弃！自 Docutils 0.22.1 起，会报告错误。
版本 7.4 新增。