应用 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 版本。

将版本与正在运行的 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: Callable[[Sphinx, Any, bool], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str

Sphinx.connect(event: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], 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

注册当 event 被触发时调用的 callback。

关于可用核心事件和回调函数参数的详细信息，请参阅 事件回调 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

注册一个新的构建器。

参数:

• builder – 一个构建器类

• override – 如果为 true，则强制安装构建器，即使已安装另一个同名的构建器

在 1.8 版本中变更: 添加 override 关键字。

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

注册一个配置值。

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

参数:

• name – 配置值的名称。建议以扩展名称为前缀（例如 html_logo, epub_title）

• default – 配置的默认值。

• rebuild –

  重建的条件。它必须是以下值之一

  • 'env' 如果设置中的更改仅在解析文档时生效 - 这意味着必须重建整个环境。

  • 'html' 如果设置中的更改需要完全重建 HTML 文档。

  • '' 如果设置中的更改不需要任何特殊重建。

• types – 配置值的类型。可以指定类型列表。例如，[str] 用于描述接受字符串值的配置。

• description – 配置值的简短描述。

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

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

在 7.4 版本中添加: description 参数。

Sphinx.add_event(name: str) → None

注册一个名为 name 的事件。

这是发出事件所必需的。

参数:

name – 事件的名称

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

注册或覆盖 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

注册一个 Docutils 节点类。

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

参数:

• node – 一个节点类

• kwargs – 每个构建器的访问器函数（见下文）

• override – 如果为 true，则强制安装节点，即使已安装另一个同名的节点

可以为 Sphinx HTML、LaTeX、text 和 manpage 编写器提供节点访问器函数作为关键字参数：关键字应为一个或多个 '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

将 Docutils 节点类注册为数字编号目标。

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

参数:

• node – 一个节点类

• figtype – 可枚举节点的类型。每个 figtype 都有单独的编号序列。作为系统 figtype，定义了 figure、table 和 code-block。可以将自定义节点添加到这些默认 figtype。如果给出了新的 figtype，也可以定义新的自定义 figtype。

• title_getter – 获取节点标题的 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

注册一个 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

注册一个 Docutils 角色。

参数:

• name – 角色的名称

• role – 一个角色函数

• override – 如果为 false，则在已安装另一个同名角色时，请勿安装它。如果为 true，则无条件安装角色。

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

在 1.8 版本中变更: 添加 override 关键字。

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

注册一个通用的 Docutils 角色。

注册一个 Docutils 角色，该角色除了将其内容包装在 nodeclass 给定的节点中之外，什么也不做。

参数:

override – 如果为 false，则在已安装另一个同名角色时，请勿安装它。如果为 true，则无条件安装角色。

添加于 0.6 版本。

在 1.8 版本中变更: 添加 override 关键字。

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

注册一个域。

参数:

• 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

在一个域中注册一个 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

在一个域中注册一个 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

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

将自定义 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

注册一个新的对象类型。

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

• 创建一个新的指令（名为 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，则即使已安装具有相同名称的 object_type，也会强制安装给定的 object_type。

在 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

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

此方法与 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

注册一个 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

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

将标准的 docutils Transform 子类 transform 添加到转换列表中，这些转换在 Sphinx 写入文档之前应用。

参数:

transform – 转换类

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

注册一个 JavaScript 文件，以包含在 HTML 输出中。

参数:

• 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() 重命名。并且它允许关键字参数作为 script 标签的属性。

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

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

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

注册一个样式表，以包含在 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() 重命名。并且它允许关键字参数作为 link 标签的属性。

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

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

注册一个包，以包含在 LaTeX 源代码中。

将 packagename 添加到 LaTeX 源代码将包含的包列表中。如果您提供 options，它将被用于 usepackage 声明。如果您将 after_hyperref 设置为真值，则该包将在 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

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

使用 lexer 来高亮显示具有给定语言 alias 的代码块。

添加于 0.6 版本。

在版本 2.1 中更改：将词法分析器类作为参数。

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

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

为 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

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

添加 getter，它必须是一个函数，其接口与 getattr() 内置函数兼容，作为 typ 实例对象的 autodoc 属性 getter。所有 autodoc 需要获取类型属性的情况都将由此函数处理，而不是 getattr()。

添加于 0.6 版本。

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

为 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_suffix 相同。用户可以使用配置设置覆盖此项。

参数:

override – 如果为 false，则在已安装相同后缀的情况下不安装。如果为 true，则无条件安装后缀。

1.8 版本新增。

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

注册一个解析器类。

参数:

override – 如果为 false，则在已为相同后缀安装另一个解析器的情况下不安装。如果为 true，则无条件安装解析器。

添加于 1.4 版本。

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

在 1.8 版本中变更: 添加 override 关键字。

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

注册一个环境收集器类。

请参阅 环境收集器 API。

1.6 版本新增。

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

注册一个 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

为 HTML 注册一个数学渲染器。

name 是数学渲染器的名称。inline_renderers 和 block_renderers 都用作 HTML writer 的访问器函数：前者用于行内数学节点 (nodes.math)，后者用于块级数学节点 (nodes.math_block)。关于访问器函数，请参阅 add_node() 了解详细信息。

1.8 版本新增。

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

注册一个消息目录。

参数:

• catalog – 目录的名称

• locale_dir – 消息目录的基本路径

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

1.8 版本新增。

Sphinx.is_parallel_allowed(typ: str) → bool

检查是否允许并行处理。

参数:

typ – 处理的类型；'read' 或 'write'。

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

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

• always：在所有页面中包含 assets

• per_page：仅在使用 assets 的页面中包含 assets

exception sphinx.application.ExtensionError

如果扩展 API 出现问题，所有这些方法都会引发此异常。

发出事件

class sphinx.application.Sphinx

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

发出 event 并将 arguments 传递给回调函数。

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

参数:

• event – 将要发出的事件的名称

• args – 事件的参数

• allowed_exceptions – 回调中允许的异常列表

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

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

发出 event 并将 arguments 传递给回调函数。

返回第一个不返回 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 = (8, 2, 0, 'final', 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)

配置文件抽象。

Config 对象使所有配置选项的值都可以作为属性使用。

它通过 Sphinx.config 和 sphinx.environment.BuildEnvironment.config 属性公开。例如，要获取 language 的值，请使用 app.config.language 或 env.config.language。

模板桥

class sphinx.application.TemplateBridge

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

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

由 builder 调用以初始化模板系统。

builder 是 builder 对象；你可能需要查看 builder.config.templates_path 的值。

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

newest_template_mtime() → float

由构建器调用，以确定输出文件是否因模板更改而过期。返回已更改的最新模板文件的 mtime。默认实现返回 0。

render(template: str, context: dict[str, Any]) → None

由构建器调用，以使用指定的上下文（Python 字典）渲染作为文件名的模板。

render_string(template: str, context: dict[str, Any]) → str

由构建器调用，以使用指定的上下文（Python 字典）渲染作为字符串的模板。

异常

exception sphinx.errors.SphinxError

Sphinx 错误的基类。

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

鼓励扩展程序从此异常派生以用于其自定义错误。

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

category

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

exception sphinx.errors.ConfigError

配置错误。

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)

扩展错误。

exception sphinx.errors.ThemeError

主题错误。

exception sphinx.errors.VersionRequirementError

不兼容的 Sphinx 版本错误。

上一页

Sphinx API

下一页

事件回调 API