公用事业¶
Sphinx提供了实用程序类和函数来开发扩展。
组件的基类¶
这些基类对于允许您的扩展获取Sphinx组件非常有用。 Config ， BuildEnvironment 以此类推)。
备注
它们的子类可能不能与纯docutil一起工作，因为它们与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)[源代码]¶
后期变换的基类。
调用后期转换来修改文档以重新构造文档以进行输出。它们解析引用、转换图像、对每种输出格式进行特殊转换等等。这个类帮助实现这些POST转换。
- class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[源代码]¶
Sphinx指令的基类。
此类为Sphinx指令提供帮助器方法。
Added in version 1.8.
备注
此类的子类可能不能与docutil一起使用。这个类与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_mailings列表。
Added in version 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 -- 内容的抵消。
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.
备注
此类的子类可能不能与docutil一起使用。这个类与Sphinx强耦合。
- property env: BuildEnvironment¶
对
BuildEnvironment对象。Added in version 2.0.
- inliner: Inliner¶
这个
docutils.parsers.rst.states.Inliner对象。
- class sphinx.util.docutils.ReferenceRole[源代码]¶
引用角色的基类。
参考角色可以接受
link title <target>角色的文本样式。解析结果；链接标题和目标将存储到self.title和self.target。Added in version 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
Sphinx.add_post_transform()
- convert(_from: str | PathLike[str], _to: str | PathLike[str]) bool[源代码]¶
将图像文件转换为预期的格式。
_from 是源图像文件的路径，并且 _to 是目标文件的路径。
- conversion_rules: list[tuple[str, str]] = []¶
图像转换器支持的转换规则。它表示为一对源图像格式(MIMETYPE)和目地One：：
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, 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
将处理程序连接到特定事件。
效用函数¶
- 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，那么标题强调线必须与周围文档中的强调线相匹配，否则行为未定义。
Added in version 7.4.