公用程序¶
Sphinx提供实用程序类和函数来开发插件。
组件的基类¶
这些基类有助于插件轻松获取Sphinx组件（例如 Config， BuildEnvironment 等等）。
备注
它们的子类可能无法与裸docutil一起工作，因为它们与Sphinx强耦合。
- class sphinx.transforms.SphinxTransform(document, startnode=None)[源代码]¶
变换的基类。
与
docutils.transforms.Transform相比，该类改进了Sphinx接口的可访问性。- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用。
- class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)[源代码]¶
后转换的基类。
后转换被调用以重组文档，用于输出。它们解析引用、转换图像、为每个输出格式进行特殊转换等等。 该类有助于实现这些后转换。
- class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[源代码]¶
Sphinx指令的基类。
这个类为Sphinx指令提供了助手方法。
在 1.8 版本加入.
备注
此类的子类可能无法与docutils一起使用。这个类与Sphinx紧密耦合。
- 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 版本加入.
- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用。在 1.8 版本加入.
- class sphinx.util.docutils.SphinxRole[源代码]¶
sphinx角色的基类。
此类为Sphinx角色提供帮助程序方法。
在 2.0 版本加入.
备注
此类的子类可能无法与docutils一起使用。这个类与Sphinx紧密耦合。
- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用。在 2.0 版本加入.
- inliner: Inliner¶
docutils.parsers.rst.states.Inliner对象。
- class sphinx.util.docutils.ReferenceRole[源代码]¶
引用角色的基类。
引用角色可以接受
link title <target>样式作为角色的文本。 解析结果； 链接标题和目标将存储到self.title和self.target。在 2.0 版本加入.
- class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)[源代码]¶
图像转换器的基类。
图像转换器是一种Docutils转换模块。 它用于将生成器不支持的图像文件转换为该生成器的适当格式。
例如，
LaTeX builder支持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]] = []¶
图像转换器支持的转换规则。它表示为源图像格式（mimetype）和目标图像格式对的列表：
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对doctree结构的常规检查，误用此选项可能导致不连贯的doctree。 在Docutils中，节节点只能是
document或section节点的子节点。keep_title_context -- 如果此值为False（默认值），则*content*将被解析为独立文档，这意味着标题装饰（例如下划线）不需要与周围文档匹配。 当解析的内容来自完全不同的上下文（例如docstrings）时，这非常有用。 如果此值为True，则标题下划线必须与周围文档中的下划线匹配，否则行为未定义。 警告：截至Docutils 0.21，装饰样式与当前节级别更高的节将被静默丢弃！ 自Docutils 0.22.1起，将报告错误。
在 7.4 版本加入.