工具¶
Sphinx 提供了实用类和函数来开发扩展.
组件的基类¶
这些基类对于允许您的扩展轻松获取 Sphinx 组件（例如 Config 、 BuildEnvironment 等）非常有用.
备注
它们的子类可能无法与裸露的 docutils 一起工作,因为它们与 Sphinx 紧密耦合.
- class sphinx.transforms.SphinxTransform(document, startnode=None)[源代码]¶
转换的基类.
与
docutils.transforms.Transform相比,此类改进了对 Sphinx API 的访问.- 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 指令提供辅助方法.
Added in version 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节点.
Added in version 7.4.
- parse_inline(text: str, *, lineno: int = -1) tuple[list[Node], list[system_message]][源代码]¶
将 text 解析为内联元素.
- 参数:
text – 要解析的文本,应为单行或段落.这不能包含任何结构元素（标题、过渡、指令等）.
lineno – 解释文本开始的行号.
- 返回:
一个节点列表（文本和内联元素）和一个 system_messages 列表.
Added in version 7.4.
- parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) list[Node][源代码]¶
将 文本 解析为节点.
- 参数:
text – 文本,以字符串形式.``StringList`` 也被接受.
allow_section_headings – 标题（章节）是否允许在 text 中?请注意,此选项会绕过 Docutils 对 doctree 结构的常规检查,滥用此选项可能导致 doctree 不一致.在 Docutils 中,章节节点应仅作为
Structural节点的子节点,包括document、section和sidebar节点.offset – 内容的偏移量.
Added in version 7.4.
- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用.Added in version 1.8.
- class sphinx.util.docutils.SphinxRole[源代码]¶
Sphinx 角色的基类.
此类为 Sphinx 角色提供辅助方法.
Added in version 2.0.
备注
这个类的子类可能无法与docutils一起工作.这个类与Sphinx紧密耦合.
- property env: BuildEnvironment¶
对
BuildEnvironment对象的引用.Added in version 2.0.
- inliner: Inliner¶
docutils.parsers.rst.states.Inliner对象.
- class sphinx.util.docutils.ReferenceRole[源代码]¶
一个用于引用角色的基类.
引用角色可以接受
链接标题 <目标>样式的文本作为角色的文本.解析结果;链接标题和目标将被存储到self.title和self.target.Added in version 2.0.
- class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)[源代码]¶
一个用于图像转换器的基类.
图像转换器是一种 Docutils 转换模块.它用于将构建器不支持的图像文件转换为该构建器适当的格式.
例如,:py:class:LaTeX 构建器 <.LaTeXBuilder> 支持 PDF、PNG 和 JPEG 作为图像格式.然而,它不支持 SVG 图像.对于这种情况,使用图像转换器允许将这些不支持的图像嵌入到文档中.其中一个图像转换器;:ref:sphinx.ext.imgconverter <sphinx.ext.imgconverter> 可以使用 Imagemagick 将 SVG 图像转换为 PNG 格式.
制作自定义图像转换器有三个步骤:
创建一个
ImageConverter类的子类重写
conversion_rules、is_available()和convert()使用
Sphinx.add_post_transform()注册你的图像转换器到 Sphinx
- 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 的事件管理器.
- 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
将处理程序连接到特定事件.
实用功能¶
- 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][源代码]¶
将 文本 解析为节点.
- 参数:
state – 状态机状态.必须是
RSTState的子类.text – 文本,以字符串形式.``StringList`` 也被接受.
source – 文本的源,在创建一个新的
StringList时使用.offset – 内容的偏移量.
allow_section_headings – 标题（章节）是否允许在 text 中?请注意,此选项会绕过 Docutils 对 doctree 结构的常规检查,滥用此选项可能导致 doctree 不一致.在 Docutils 中,章节节点应仅作为
Structural节点的子节点,包括document、section和sidebar节点.keep_title_context – 如果这是False（默认值）,那么*内容*将被解析为独立文档,这意味着标题装饰（例如下划线）不需要与周围文档匹配.这在解析的内容来自完全不同的上下文（例如文档字符串）时非常有用.如果这是True,那么标题下划线必须与周围文档中的匹配,否则行为未定义.
Added in version 7.4.