应用程序 API

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

class sphinx.application.Sphinx

此应用程序对象具有以下所述的公共 API。

扩展设置

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

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

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, list[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: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], Sequence[str]], None], 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, bool], str | None, str | None], tuple[str | None, str | None] | None], priority: int = 500) → int

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

注册 *callback* 以在发出 *event* 时调用。

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

参数:

• event – 目标事件的名称

• callback – 事件的回调函数

• priority – 回调的优先级。回调将按照 *priority* （升序）的顺序调用。

返回值：

监听器 ID。它可用于 disconnect()。

版本 3.0 中的变化： 支持 *priority*

Sphinx.disconnect(listener_id: int) → None

通过 *listener_id* 注销回调。

参数:

listener_id – connect() 返回的监听器 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 值是可调用对象，它将使用 config 对象作为其参数来获取默认值。这可以用于实现其默认值取决于其他值的配置值。

版本 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: tuple[Callable, Callable | None]) → None

注册 Docutils 节点类。

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

参数:

• node – 节点类

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

• override – 如果为 True，则强制安装节点，即使另一个节点已以相同名称安装

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

class math(docutils.nodes.Element): pass

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[Callable, Callable]) → None

将 Docutils 节点类注册为 numfig 目标。

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

注册 Docutils 指令。

参数:

• name – 指令的名称

• cls – 指令类

• override – 如果为假，则如果另一个指令已作为相同名称安装，则不安装它；如果为真，则无条件安装指令。

例如，名为 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):
        ...

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 – 如果为假，则如果另一个角色已作为相同名称安装，则不安装它；如果为真，则无条件安装角色。

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

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

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

注册通用 Docutils 角色。

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

参数:

override – 如果为假，则如果另一个角色已作为相同名称安装，则不安装它；如果为真，则无条件安装角色。

版本 0.6 中新增。

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

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

注册域。

参数:

• domain – 域类

• override – 如果为假，则如果另一个域已作为相同名称安装，则不安装它；如果为真，则无条件安装域。

版本 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 – 如果为假，则如果另一个指令已作为相同名称安装，则不安装它；如果为真，则无条件安装指令。

版本 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 – 如果为假，则如果另一个角色已作为相同名称安装，则不安装它；如果为真，则无条件安装角色。

版本 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 | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence = (), override: bool = False) → None

注册新的对象类型。

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

• 创建一个新的指令（称为 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。

版本 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 – 如果为假，则如果另一个交叉引用类型已安装为相同名称，则不安装它；如果为真，则无条件安装交叉引用类型。

版本 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	完成并清理。

参考文献： Transform Priority Range Categories

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

注册一个要包含在 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 中的更改： 采用优先级参数。允许将 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() 重命名。并且它允许关键字参数作为链接标记的属性。

版本 3.5 中的更改： 采用优先级参数。允许将 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 属性获取器。所有 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) → None

注册 HTML 主题。

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

版本 1.6 中新增。

Sphinx.add_html_math_renderer(name: str, inline_renderers: tuple[Callable, Callable | None] | None = None, block_renderers: tuple[Callable, Callable | None] | None = None) → None

为 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) → None

注册消息目录。

参数:

• catalog – 目录的名称

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

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

版本 1.8 中新增。

Sphinx.is_parallel_allowed(typ: str) → bool

检查是否允许并行处理。

参数:

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

exception sphinx.application.ExtensionError

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

发出事件

class sphinx.application.Sphinx

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

发出 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

存储序列化 doctree 的目录。

Sphinx.outdir

存储构建文档的目录。

Sphinx.fresh_env_used

表示是否为本次构建创建了新的环境，True/False，如果环境尚未初始化则为 None。

Sphinx 核心事件

注意

已移至 事件回调 API。

检查 Sphinx 版本

用于使您的扩展适应 Sphinx 中的 API 更改。

sphinx.version_info = (8, 1, 0, '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)

配置文件抽象。

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.config.templates_path 的值。

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

newest_template_mtime() → float

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

render(template: str, context: dict) → None

由构建器调用以渲染以文件名形式给定的模板，并指定上下文（一个 Python 字典）。

render_string(template: str, context: dict) → 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