应用程序 API¶

每个 Sphinx 扩展都是一个 Python 模块，至少包含一个 setup() 函数。此函数在初始化时调用，带有一个参数，即表示 Sphinx 进程的应用程序对象。

class sphinx.application.Sphinx[源]¶: 此应用程序对象具有以下描述的公共 API。

扩展设置¶

这些方法通常在扩展的 setup() 函数中调用。

使用 Sphinx 扩展 API 的示例可以在 sphinx.ext 包中找到。

Sphinx.setup_extension(extname: str) → None[源]¶

导入并设置 Sphinx 扩展模块。

加载由模块 name 给定的扩展。如果您的扩展需要另一个扩展提供的功能，请使用此方法。如果调用两次，则无操作。

static Sphinx.require_sphinx(version: tuple[int, int] | str) → None[源]¶

检查 Sphinx 版本（如果请求）。

将 version 与正在运行的 Sphinx 版本进行比较，如果版本过旧则中止构建。

参数:: version – 所需版本，格式为 major.minor 或 (major, minor)。

版本 1.0 新增。

在 7.1 版本中更改: version 的类型现在允许 (major, minor) 形式。

Sphinx.connect(event: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int = 500) → int

Sphinx.connect(event: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int = 500) → int

Sphinx.connect(event: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int = 500) → int

Sphinx.connect(event: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int = 500) → int

Sphinx.connect(event: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int = 500) → int

Sphinx.connect(event: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int = 500) → int

Sphinx.connect(event: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int = 500) → int

Sphinx.connect(event: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int = 500) → int

Sphinx.connect(event: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int = 500) → int

Sphinx.connect(event: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int = 500) → int

Sphinx.connect(event: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int = 500) → int

Sphinx.connect(event: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int = 500) → int

Sphinx.connect(event: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int = 500) → int

Sphinx.connect(event: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int = 500) → int

Sphinx.connect(event: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-before-process-signature'], callback: _AutodocBeforeProcessSignatureListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-signature'], callback: _AutodocProcessSignatureListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-bases'], callback: _AutodocProcessBasesListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-skip-member'], callback: _AutodocSkipMemberListener, priority: int = 500) → int

Sphinx.connect(event: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int = 500) → int

Sphinx.connect(event: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int = 500) → int

Sphinx.connect(event: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int = 500) → int

Sphinx.connect(event: str, callback: Callable[..., Any], priority: int = 500) → int

注册 callback 以在 event 触发时调用。

有关可用核心事件和回调函数参数的详细信息，请参阅事件回调 API。

参数:

event – 目标事件的名称
callback – 事件的回调函数
priority – 回调的优先级。回调将按 priority 的顺序（升序）调用。

返回:

一个侦听器 ID。它可用于 disconnect()。

在 3.0 版本中更改: 支持 priority

Sphinx.disconnect(listener_id: int) → None[源]¶

通过 listener_id 注销回调。

参数:: listener_id – connect() 返回的 listener_id

Sphinx.add_builder(builder: type[Builder], override: bool = False) → None[source]¶

注册一个新的构建器。

参数:

builder – 一个构建器类
override – 如果为 True，即使已存在同名构建器，也会强制安装此构建器

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_config_value(name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '') → None[source]¶

注册一个配置值。

这对于 Sphinx 识别新值并相应设置默认值是必要的。

参数:

name – 配置值的名称。建议以扩展名作为前缀（例如 html_logo, epub_title）
default – 配置的默认值。
rebuild –
重建条件。它必须是以下值之一：
- 'env' 如果设置中的更改仅在文档被解析时生效——这意味着整个环境必须重建。
- 'html' 如果设置中的更改需要完全重建 HTML 文档。
- '' 如果设置中的更改不需要任何特殊的重建。
types – 配置值的类型。可以指定类型列表。例如，[str] 用于描述接受字符串值的配置。
description – 配置值的简短描述。

0.4 版本中已更改: 如果 default 值是可调用对象，它将以配置对象作为参数被调用，以获取默认值。这可用于实现默认值取决于其他值的配置值。

0.6 版本中已更改: 将 rebuild 从简单的布尔值（等同于 '' 或 'env'）更改为字符串。但是，布尔值仍然被接受并在内部转换。

1.4 版本中新增: types 参数。

7.4 版本中新增: description 参数。

Sphinx.add_event(name: str) → None[source]¶

注册一个名为 name 的事件。

这是为了能够发出它而必需的。

参数:: name – 事件的名称

Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) → None[source]¶

注册或覆盖一个 Docutils 翻译器类。

这用于注册一个自定义输出翻译器或替换一个内置翻译器。这允许扩展使用自定义翻译器并为翻译器定义自定义节点（参见 add_node()）。

参数:

name – 翻译器构建器的名称
translator_class – 翻译器类
override – 如果为 True，即使已存在同名翻译器，也会强制安装此翻译器

版本 1.3 中添加。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: _NodeHandlerPair) → None[source]¶

注册 Docutils 节点类。

这对于 Docutils 内部是必要的。未来也可能用于验证已解析文档中的节点。

参数:

node – 节点类
kwargs – 每个构建器的访问器函数（见下文）
override – 如果为 True，即使已存在同名节点，也会强制安装此节点

Sphinx HTML、LaTeX、文本和手册页编写器的节点访问器函数可以作为关键字参数给出：关键字应为 'html'、'latex'、'text'、'man'、'texinfo' 或任何其他受支持的翻译器中的一个或多个，值为 (visit, depart) 方法的 2 元组。depart 可以是 None，如果 visit 函数引发 docutils.nodes.SkipNode。示例

class math(docutils.nodes.Element): ...

def visit_math_html(self, node):
    self.body.append(self.starttag(node, 'math'))

def depart_math_html(self, node):
    self.body.append('</math>')

app.add_node(math, html=(visit_math_html, depart_math_html))

显然，对于您未指定访问器方法的翻译器，当文档中遇到要翻译的节点时，它们将无法处理该节点。

0.5 版本中已更改: 添加了对提供访问器函数的关键字参数的支持。

Sphinx.add_enumerable_node(node: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[_NodeHandler, _NodeHandler]) → None[source]¶

注册 Docutils 节点类作为可编号目标。

Sphinx 会自动编号节点。然后用户可以使用 numref 引用它。

参数:

node – 节点类
figtype – 可编号节点的类型。每个 figtype 都有独立的编号序列。作为系统 figtype，定义了 figure、table 和 code-block。可以将自定义节点添加到这些默认 figtype 中。如果给定了新的 figtype，也可以定义新的自定义 figtype。
title_getter – 获取节点标题的函数。它接受一个可编号节点实例，并且必须将其标题作为字符串返回。该标题用于 ref 引用的默认标题。默认情况下，Sphinx 从节点中搜索 docutils.nodes.caption 或 docutils.nodes.title 作为标题。
kwargs – 每个构建器的访问器函数（与 add_node() 相同）
override – 如果为 True，即使已存在同名节点，也会强制安装此节点

版本 1.4 中新增。

Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) → None[source]¶

注册一个 Docutils 指令。

参数:

name – 指令的名称
cls – 指令类
override – 如果为 false，如果已安装了同名指令则不安装它。如果为 true，则无条件安装该指令。

例如，一个名为 my-directive 的自定义指令将像这样添加：

from docutils.parsers.rst import Directive, directives

class MyDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        pass

def setup(app):
    app.add_directive('my-directive', MyDirective)

有关更多详细信息，请参阅 Docutils 文档。

0.6 版本中已更改: 现在支持 Docutils 0.5 风格的指令类。

1.8 版本中已更改: Docutils 0.4 风格（基于函数）的指令支持已弃用。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_role(name: str, role: Any, override: bool = False) → None[source]¶

注册一个 Docutils 角色。

参数:

name – 角色的名称
role – 角色函数
override – 如果为 false，如果已安装了同名角色则不安装它。如果为 true，则无条件安装该角色。

有关角色函数的更多详细信息，请参阅 Docutils 文档。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) → None[source]¶

注册一个通用的 Docutils 角色。

注册一个 Docutils 角色，它除了将其内容包装在 nodeclass 给定的节点中之外，不执行任何操作。

参数:: override – 如果为 false，如果已安装了同名角色则不安装它。如果为 true，则无条件安装该角色。

0.6 版本新增。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_domain(domain: type[Domain], override: bool = False) → None[source]¶

注册一个域。

参数:

domain – 一个域类
override – 如果为 false，则如果已存在同名域，则不安装它。如果为 true，则无条件安装该域。

版本 1.0 新增。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[Directive], override: bool = False) → None[source]¶

在域中注册一个 Docutils 指令。

与 add_directive() 类似，但指令被添加到名为 domain 的域中。

参数:

domain – 目标域的名称
name – 指令的名称
cls – 指令类
override – 如果为 false，如果已安装了同名指令则不安装它。如果为 true，则无条件安装该指令。

版本 1.0 新增。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) → None[source]¶

在域中注册一个 Docutils 角色。

与 add_role() 类似，但角色被添加到名为 domain 的域中。

参数:

domain – 目标域的名称
name – 角色的名称
role – 角色函数
override – 如果为 false，如果已安装了同名角色则不安装它。如果为 true，则无条件安装该角色。

版本 1.0 新增。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) → None[source]¶

为域注册一个自定义索引。

将自定义 index 类添加到名为 domain 的域中。

参数:

domain – 目标域的名称
index – 索引类
override – 如果为 false，如果已安装了同名索引则不安装它。如果为 true，则无条件安装该索引。

版本 1.0 新增。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable[[BuildEnvironment, str, addnodes.desc_signature], str] | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence[Field] = (), override: bool = False) → None[source]¶

注册一个新的对象类型。

此方法是添加可以交叉引用的新对象类型的非常方便的方式。它将执行以下操作：

创建一个新的指令（称为 directivename），用于记录对象。如果 indextemplate 不为空，它将自动添加索引条目；如果给出，它必须包含且仅包含一个 %s 实例。有关模板如何解释的示例，请参阅下面的示例。
创建一个新的角色（称为 rolename），用于交叉引用这些对象描述。
如果您提供了 parse_node，它必须是一个函数，接受一个字符串和一个 Docutils 节点，并且必须用从字符串解析的子节点填充该节点。然后它必须返回将用于交叉引用和索引条目的项的名称。有关示例，请参阅此文档源中的 conf.py 文件。
objname（如果未给出，则默认为 directivename）命名对象的类型。它用于列出对象，例如在搜索结果中。

例如，如果您在自定义 Sphinx 扩展中有以下调用：

app.add_object_type('directive', 'dir', 'pair: %s; directive')

您可以在文档中使用以下标记：

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

对于指令，将生成一个索引条目，就好像您已预先添加了：

.. index:: pair: function; directive

除非您给出 ref_nodeclass 参数（它必须是 Docutils 节点类），否则引用节点将是 literal 类（因此它将以比例字体渲染，适合代码）。最有用的是 docutils.nodes.emphasis 或 docutils.nodes.strong – 如果您不希望有进一步的文本装饰，也可以使用 docutils.nodes.generated。如果文本应被视为字面值（例如，不进行智能引号替换），但不具有打字机样式，请使用 sphinx.addnodes.literal_emphasis 或 sphinx.addnodes.literal_strong。

对于角色内容，您拥有与标准 Sphinx 角色相同的句法可能性（参见语法）。

如果 override 为 True，即使已存在同名对象类型，也会强制安装给定的对象类型。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', override: bool = False) → None[source]¶

注册一个新的交叉引用对象类型。

此方法与 add_object_type() 非常相似，不同之处在于它生成的指令必须为空，并且不会产生任何输出。

这意味着您可以向源代码添加语义目标，并使用自定义角色而不是通用角色（如 ref）来引用它们。示例调用

app.add_crossref_type(
    'topic', 'topic', 'single: %s', docutils.nodes.emphasis
)

示例用法

.. topic:: application API

The application API
-------------------

Some random text here.

See also :topic:`this section <application API>`.

（当然，topic 指令后面的元素不必是节。）

参数:: override – 如果为 false，如果已安装了同名交叉引用类型则不安装它。如果为 true，则无条件安装该交叉引用类型。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_transform(transform: type[Transform]) → None[source]¶

注册一个 Docutils 转换，在解析后应用。

将标准 Docutils Transform 子类 transform 添加到 Sphinx 解析 reST 文档后应用的转换列表中。

参数:: transform – 转换类

Sphinx 转换的优先级范围类别¶
优先级	Sphinx 的主要目的
0-99	通过 Docutils 修复无效节点。翻译文档树。
100-299	准备
300-399	早
400-699	主要
700-799	后处理。修改文本和引用的截止日期。
800-899	收集引用和被引用节点。域处理。
900-999	完成和清理。

参考：转换优先级范围类别

Sphinx.add_post_transform(transform: type[Transform]) → None[source]¶

注册一个 Docutils 转换，在写入前应用。

将标准 Docutils Transform 子类 transform 添加到 Sphinx 写入文档前应用的转换列表中。

参数:: transform – 转换类

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) → None[source]¶

注册一个要包含在 HTML 输出中的 JavaScript 文件。

参数:

filename – 默认 HTML 模板将包含的 JavaScript 文件名。它必须相对于 HTML 静态路径，或者是一个带有方案的完整 URI，或者为 None。 None 值用于创建内联 <script> 标签。参见下面 kwargs 的描述。
priority – 文件按优先级升序包含。如果多个 JavaScript 文件具有相同的优先级，则这些文件将按注册顺序包含。参见下面“JavaScript 文件的优先级范围”列表。
loading_method – JavaScript 文件的加载方法。允许 'async' 或 'defer'。
kwargs – 额外的关键字参数作为 <script> 标签的属性包含。如果提供了特殊关键字参数 body，其值将作为 <script> 标签的内容添加。

示例

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', loading_method='async')
# => <script src="_static/example.js" async="async"></script>

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>

JavaScript 文件的优先级范围¶
优先级	Sphinx 的主要目的
200	内置 JavaScript 文件的默认优先级
500	扩展的默认优先级
800	`html_js_files` 的默认优先级

当扩展程序在 html-page-context 事件上调用此方法时，可以将 JavaScript 文件添加到特定的 HTML 页面。

版本 0.5 中新增。

1.8 版本中已更改: 从 app.add_javascript() 重命名。并允许关键字参数作为脚本标签的属性。

3.5 版本中已更改: 接受 priority 参数。允许将 JavaScript 文件添加到特定页面。

4.4 版本中已更改: 接受 loading_method 参数。允许更改 JavaScript 文件的加载方法。

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None[source]¶

注册一个样式表以包含在 HTML 输出中。

参数:

filename – 默认 HTML 模板将包含的 CSS 文件名。它必须是相对于 HTML 静态路径的路径，或者是带方案的完整 URI。
priority – 文件按优先级升序包含。如果多个 CSS 文件具有相同的优先级，则这些文件将按注册顺序包含。参见下面“CSS 文件的优先级范围”列表。
kwargs – 额外的关键字参数作为 <link> 标签的属性包含。

示例

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

CSS 文件的优先级范围¶
优先级	Sphinx 的主要目的
200	内置 CSS 文件的默认优先级
500	扩展的默认优先级
800	`html_css_files` 的默认优先级

当扩展程序在 html-page-context 事件上调用此方法时，可以将 CSS 文件添加到特定的 HTML 页面。

版本 1.0 新增。

1.6 版本中已更改: 可选的 alternate 和/或 title 属性可以通过参数 alternate（布尔值）和 title（字符串）提供。默认情况下没有标题，且 alternate = False。有关更多信息，请参阅文档。

1.8 版本中已更改: 从 app.add_stylesheet() 重命名。并允许关键字参数作为链接标签的属性。

3.5 版本中已更改: 接受 priority 参数。允许将 CSS 文件添加到特定页面。

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) → None[source]¶

注册一个要包含在 LaTeX 源代码中的宏包。

将 packagename 添加到 LaTeX 源代码将包含的宏包列表中。如果您提供 options，它将被用于 usepackage 声明。如果您将 after_hyperref 设置为 True，则该宏包将在 hyperref 宏包之后加载。

app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

版本 1.3 中添加。

3.1 版本中新增: after_hyperref 选项。

Sphinx.add_lexer(alias: str, lexer: type[Lexer]) → None[source]¶

注册一个新的源代码词法分析器。

使用 lexer 以给定语言 alias 突出显示代码块。

0.6 版本新增。

2.1 版本中已更改: 接受一个词法分析器类作为参数。

4.0 版本中已更改: 移除了对词法分析器实例作为参数的支持。

Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) → None[source]¶

为 autodoc 扩展注册一个新的文档器类。

将 cls 添加为 sphinx.ext.autodoc 扩展的新文档器类。它必须是 sphinx.ext.autodoc.Documenter 的子类。这允许自动文档化新型对象。有关如何子类化 Documenter 的示例，请参阅 autodoc 模块的源代码。

如果 override 为 True，即使已存在同名文档器，也会强制安装给定的 cls。

参见开发 autodoc 扩展。

0.6 版本新增。

2.2 版本中已更改: 添加了 override 关键字。

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) → None[source]¶

为 autodoc 扩展注册一个新的类似 getattr 的函数。

将 getter 添加为 typ 实例的对象的 autodoc 属性获取器，该函数必须具有与内置函数 getattr() 兼容的接口。然后，autodoc 需要获取属性的所有情况都将由该函数处理，而不是 getattr()。

0.6 版本新增。

Sphinx.add_search_language(cls: type[SearchLanguage]) → None[source]¶

为 HTML 搜索索引注册一种新语言。

将 cls（必须是 sphinx.search.SearchLanguage 的子类）添加为构建 HTML 全文搜索索引的支持语言。该类必须具有一个 lang 属性，指示它应使用的语言。参见 html_search_language。

版本 1.1 新增。

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) → None[source]¶

注册源文件后缀。

与 source_suffix 相同。用户可以使用配置设置覆盖此项。

参数:: override – 如果为 false，如果已安装相同后缀则不安装它。如果为 true，则无条件安装该后缀。

版本 1.8 中新增。

Sphinx.add_source_parser(parser: type[Parser], override: bool = False) → None[source]¶

注册一个解析器类。

参数:: override – 如果为 false，如果已为相同后缀安装了其他解析器，则不安装它。如果为 true，则无条件安装该解析器。

版本 1.4 中新增。

1.8 版本中已更改: suffix 参数已弃用。它只接受 parser 参数。请使用 add_source_suffix() API 代替注册后缀。

1.8 版本中已更改: 添加了 override 关键字。

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None[source]¶

注册一个环境收集器类。

参考环境收集器 API。

版本 1.6 中新增。

Sphinx.add_html_theme(name: str, theme_path: str | os.PathLike[str]) → None[source]¶

注册一个 HTML 主题。

name 是主题的名称，theme_path 是主题的完整路径（参考：将您的主题作为 Python 包分发）。

版本 1.6 中新增。

Sphinx.add_html_math_renderer(name: str, inline_renderers: _MathsInlineRenderers | None = None, block_renderers: _MathsBlockRenderers | None = None) → None[source]¶

为 HTML 注册数学渲染器。

name 是数学渲染器的名称。inline_renderers 和 block_renderers 都用作 HTML 编写器的访问器函数：前者用于内联数学节点（nodes.math），后者用于块数学节点（nodes.math_block）。关于访问器函数，请参见 add_node() 获取详细信息。

版本 1.8 中新增。

Sphinx.add_message_catalog(catalog: str, locale_dir: str | os.PathLike[str]) → None[source]¶

注册消息目录。

参数:

catalog – 目录的名称
locale_dir – 消息目录的基本路径

有关更多详细信息，请参见 sphinx.locale.get_translation()。

版本 1.8 中新增。

Sphinx.is_parallel_allowed(typ: str) → bool[source]¶

检查是否允许并行处理。

参数:: typ – 处理类型；'read' 或 'write'。

Sphinx.set_html_assets_policy(policy: Literal['always', 'per_page']) → None[source]¶

设置在 HTML 页面中包含资产的策略。

always: 在所有页面中都包含资产
per_page: 仅在使用了资产的页面中包含它们

exception sphinx.application.ExtensionError¶: 如果扩展 API 出现问题，所有这些方法都会引发此异常。

触发事件¶

注意

扩展开发者应优先直接使用事件管理器（events）对象，通过 EventManager.emit() 和 EventManager.emit_firstresult()，它们与下面的方法行为相同。

class sphinx.application.Sphinx[source]

emit(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[Any][source]¶

触发 *事件* 并将 *参数* 传递给回调函数。

返回所有回调函数的返回值列表。不要在扩展中触发核心 Sphinx 事件！

参数:

event – 将要触发的事件名称
args – 事件的参数
allowed_exceptions – 回调中允许的异常列表

3.1 版中更改: 添加了 allowed_exceptions 以指定直通异常

emit_firstresult(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any[source]¶

触发 *事件* 并将 *参数* 传递给回调函数。

返回第一个不返回 None 的回调的结果。

参数:

event – 将要触发的事件名称
args – 事件的参数
allowed_exceptions – 回调中允许的异常列表

版本 0.5 中新增。

3.1 版中更改: 添加了 allowed_exceptions 以指定直通异常

Sphinx 运行时信息¶

应用程序对象还通过属性提供运行时信息。

Sphinx.project¶: 目标项目。参见 Project。

Sphinx.srcdir¶: 源目录。

Sphinx.confdir¶: 包含 conf.py 的目录。

Sphinx.doctreedir¶: 用于存储 pickled doctrees 的目录。

Sphinx.outdir¶: 用于存储构建文档的目录。

Sphinx.fresh_env_used¶: 如果为本次构建创建了新环境，则为 True/False，如果环境尚未初始化，则为 None。

Sphinx 核心事件¶

注意

已移至事件回调 API。

检查 Sphinx 版本¶

使用此功能来使您的扩展适应 Sphinx 中的 API 更改。

sphinx.version_info: Final = (9, 0, 1, 'beta', 0)¶

版本信息，以便更好地进行编程使用。

一个包含五个元素的元组；对于 Sphinx 版本 1.2.1 beta 3，这将是 (1, 2, 1, 'beta', 3)。第四个元素可以是以下之一：alpha、beta、rc、final。final 的最后一个元素始终为 0。

1.2 版新增: 在 1.2 版之前，请检查字符串 sphinx.__version__。

Config 对象¶

class sphinx.config.Config(config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None)[source]¶

配置文件抽象。

Config 对象将所有配置选项的值作为属性提供。

它通过 Sphinx.config 和 sphinx.environment.BuildEnvironment.config 属性暴露。例如，要获取 language 的值，可以使用 app.config.language 或 env.config.language。

模板桥¶

class sphinx.application.TemplateBridge[source]¶

此类定义了“模板桥”的接口，即一个根据模板名称和上下文渲染模板的类。

init(builder: Builder, theme: Theme | None = None, dirs: list[str] | None = None) → None[source]¶

由构建器调用以初始化模板系统。

builder 是构建器对象；你可能想要查看 builder.config.templates_path 的值。

theme 是一个 sphinx.theming.Theme 对象或 None；在后一种情况下，dirs 可以是用于查找模板的固定目录列表。

newest_template_mtime() → float[source]¶: 由构建器调用，以确定输出文件是否因模板更改而过时。返回最新更改的模板文件的修改时间。默认实现返回 0。

render(template: str, context: dict[str, Any]) → None[source]¶: 由构建器调用，以使用指定上下文（一个 Python 字典）渲染作为文件名给出的模板。

render_string(template: str, context: dict[str, Any]) → str[source]¶: 由构建器调用，以使用指定上下文（一个 Python 字典）渲染作为字符串给出的模板。

异常¶

exception sphinx.errors.SphinxError[source]¶

Sphinx 错误的基类。

这是“友好”异常的基类。当引发此类异常时，Sphinx 将中止构建并将异常类别和消息呈现给用户。

鼓励扩展派生自此异常以处理其自定义错误。

不派生自 SphinxError 的异常被视为意外，并向用户显示部分回溯（完整回溯保存在临时文件中）。

category¶: 异常“类别”的描述，用于将异常转换为字符串（“类别：消息”）。应在子类中相应设置。

exception sphinx.errors.ConfigError[source]¶: 配置错误。

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)[source]¶: 扩展错误。

exception sphinx.errors.ThemeError[source]¶: 主题错误。

exception sphinx.errors.VersionRequirementError[source]¶: 不兼容的 Sphinx 版本错误。