Application API

每个 Sphinx 插件是一个 Python 模块，至少有一个 setup() 函数。这个函数在初始化时被调用，有一个参数，代表 Sphinx 进程的应用对象。

class sphinx.application.Sphinx

该应用对象具有以下描述的公共 API。

插件设置

这些方法通常在一个插件的 setup() 函数中调用。

使用 Sphinx 插件 API 的例子可以在 sphinx.ext 包中看到。

Sphinx.setup_extension(extname: str) → None

导入并设置一个 Sphinx 插件模块。

加载由模块 name 给出的插件。如果你的插件需要另一个插件提供的功能，请使用此功能。如果调用两次，则没有作用。

Sphinx.require_sphinx(version: str) → None

如果有要求，请检查 Sphinx 的版本。

将 version 与运行中的 Sphinx 的版本进行比较，当它太旧时就中止构建。

参数

version – 所需的版本，形式为 major.minor。

1.0 新版功能.

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

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

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

参数

• event – 目标事件的名称

• callback – 事件的回调函数

• 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

参数

• builder – builder 类

• override – 如果为真，则强制安装该构建器，即使已经安装了同名的其他构建器

在 1.8 版更改: 添加 override 关键字

Sphinx.add_config_value(name: str, default: Any, rebuild: Union[bool, str], types: Any = ()) → None

注册配置值。

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

参数

• name – 配置值的名称。推荐使用扩展名作为前缀（例如 html_logo、epub_title）

• default – 配置的缺省值。

• rebuild –

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

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

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

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

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

在 0.4 版更改: 如果 default 值是可调用的，它将被调用配置对象作为它的参数，以获得默认值。这可以用来实现那些默认值依赖于其他值的配置值。

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

Sphinx.add_event(name: str) → None

注册名为 name 的事件。

这是能够 emit 它所需要的。

参数

name – 事件的名称

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

注册或覆盖 Docutil translator 类。

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

参数

• name – translator 的 builder 名称

• translator_class – translator 类

• override – 如果为真，则强制安装 translator，即使已经安装了另一个同名的 translator

1.3 新版功能.

在 1.8 版更改: 添加 override 关键字

Sphinx.add_node(node: Type[docutils.nodes.Element], override: bool = False, **kwargs: Tuple[Callable, Optional[Callable]]) → None

注册 Docutils 节点类。

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

参数

• node – 节点类

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

• override – 如果为真，则强制安装该节点，即使已经安装了同名节点

Sphinx HTML、LaTeX、text 和 manpage 的节点访问者函数可以作为关键字参数给出：关键字应该是 'html'、'latex'、'text'、'man'、'texinfo' 或任何其他受支持的 translator 的一个或多个，值为 (visit,depart) 方法的二元组。如果 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))

很明显，如果你没有为 translator 指定访问者方法，那么当你在翻译文档时，它会在节点上阻塞。

在 0.5 版更改: 增加了对访问函数关键字参数的支持。

Sphinx.add_enumerable_node(node: Type[docutils.nodes.Element], figtype: str, title_getter: Optional[Callable[[docutils.nodes.Node], str]] = None, override: bool = False, **kwargs: Tuple[Callable, Callable]) → None

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

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

参数

• node – 节点类

• figtype – 可枚举节点的类型。每种图形都有各自的编号顺序。系统 figtype 定义了 figure、table 和 code-block。可以向这些默认图形类型添加定制节点。如果给出了新的 figtype，也可以定义新的自定义 figtype。

• title_getter – 获取节点标题的 getter 函数。它接受可枚举节点的实例，并且必须以字符串形式返回其标题。title 用于 ref 引用的默认标题。默认情况下，Sphinx 从节点中搜索 docutils.nodes.caption 或 docutils.nodes.title 作为标题。

• kwargs – 每个构建器的访问函数（与 add_node() 相同）

• override – 如果为真，则强制安装该节点，即使已经安装了同名节点

1.4 新版功能.

Sphinx.add_directive(name: str, cls: Type[docutils.parsers.rst.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 docs 。

在 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 docs。

在 1.8 版更改: 添加 override 关键字

Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool = False) → None

注册通用 Docutils 角色

注册不做任何事情的 Docutils 角色，它只是将其内容包装在由 nodeclass 给出的节点中。

如果 override 为 True，则给定的 nodeclass 会被强制安装，即使已经安装了名为 name 的角色。

0.6 新版功能.

在 1.8 版更改: 添加 override 关键字

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

注册域

参数

• domain – 域类

• override – 如果为真，则强制安装该域名，即使已经安装了同名域名

1.0 新版功能.

在 1.8 版更改: 添加 override 关键字

Sphinx.add_directive_to_domain(domain: str, name: str, cls: Type[docutils.parsers.rst.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: Union[Callable[[str, str, str, int, docutils.parsers.rst.states.Inliner, Dict[str, Any], List[str]], Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]], sphinx.roles.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[sphinx.domains.Index], override: bool = False) → None

为域注册自定义索引。

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

参数

• domain – 目标域的名称

• index – 索引类

• override – 如果为真，则强制安装索引，即使已经安装了同名的索引

1.0 新版功能.

在 1.8 版更改: 添加 override 关键字

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Optional[Callable] = None, ref_nodeclass: Optional[Type[docutils.nodes.TextElement]] = None, objname: str = '', doc_field_types: List = [], override: bool = False) → None

注册新的 object 类型。

这个方法是一种非常方便的方式来添加新的 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

引用节点将是 literal 类（因此它将以比例字体呈现，适合于代码），除非你给出 ref_nodeclass 参数，它必须是 docutils 节点类。最有用的是 docutils.nodes.emphasis 或 docutils.nodes.strong —— 你也可以使用 docutils.nodes.generated，如果你不想要进一步的文本装饰。如果文本应该被视为 literal（例如，没有智能引用替换），但没有 typewriter 样式，使用 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: Optional[Type[docutils.nodes.TextElement]] = None, objname: str = '', override: bool = False) → None

注册新的 crossref 对象类型

这个方法非常类似 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 指令后面的元素不必是 section。)

如果 override 为True，则给定的 crossref_type 被强制安装，即使已经安装了同名的 crossref_type。

在 1.8 版更改: 添加 override 关键字

Sphinx.add_transform(transform: Type[docutils.transforms.Transform]) → None

注册要在解析后应用的 Docutils 变换。

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

参数

transform – transform 类

Sphinx 变换的优先级范围类别

优先级	Sphinx 的主要用途
0-99	通过 docutils 修复无效节点。翻译 doctree。
100-299	准备
300-399	早期
400-699	main
700-799	后处理。修改文本和引用的截止日期。
800-899	收集引用节点和被引用节点。域处理。
900-999	Finalize and clean up.

查看：变换优先范围类别

Sphinx.add_post_transform(transform: Type[docutils.transforms.Transform]) → None

在编写之前注册要应用的 Docutils 变换。

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

参数

transform – transform 类

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

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

参数

• filename – The filename of the JavaScript file. It must be relative to the HTML static path, a full URI with scheme, or None value. The None value is used to create inline <script> tag. See the description of kwargs below.

• priority – The priority to determine the order of <script> tag for JavaScript files. See list of “prority range for JavaScript files” below. If the priority of the JavaScript files it the same as others, the JavaScript files will be loaded in order of registration.

• loading_method – The loading method of the JavaScript file. 'async' or 'defer' is allowed.

• kwargs – Extra keyword arguments are included as attributes of the <script> tag. A special keyword argument body is given, its value will be added between the <script> tag.

示例

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 的 argument。允许添加 JavaScript 文件到特定的页面。

在 4.4 版更改: Take loading_method argument. Allow to change the loading method of the JavaScript file.

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

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

参数

• filename – The filename of the CSS file. It must be relative to the HTML static path, or a full URI with scheme.

• priority – The priority to determine the order of <link> tag for the CSS files. See list of “prority range for CSS files” below. If the priority of the CSS files it the same as others, the CSS files will be loaded in order of registration.

• kwargs – Extra keyword arguments are included as attributes of the <link> tag.

示例

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 的 argument。允许添加 CSS 文件到特定的页面。

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

注册包含在 LaTeX 源代码中的包。

将 packagename 添加到 LaTeX 源代码将包含的包列表中。如果你提供 options，它将被带到 usepackage 声明中。如果你设置 after_hyperref truthy，这个包将会在 hyperref package 之后被加载。

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[pygments.lexer.Lexer]) → None

为源代码注册新的 lexer。

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

0.6 新版功能.

在 2.1 版更改: 把 lexer 类作为参数。在 Sphinx-3.x 之前，lexer 的实例仍然受到支持。

Sphinx.add_autodocumenter(cls: Any, override: bool = False) → None

为 autodoc 插件注册新的文档器类。

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

如果 override 为True，则给定的 cls 被强制安装，即使已经安装了同名文档。

查阅 为 IntEnum 开发 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: Any) → 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。用户可以通过 config 设置来覆盖它。

如果 override 为True，则给定的 suffix 被强制安装，即使已经安装了相同的后缀。

1.8 新版功能.

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

注册 parser 类。

如果 override 为 True，则给定的 parser 被强制安装，即使已经安装了相同后缀的解析器。

1.4 新版功能.

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

在 1.8 版更改: 添加 override 关键字

Sphinx.add_env_collector(collector: Type[sphinx.environment.collectors.EnvironmentCollector]) → None

注册环境收集器类。

指的是 Environment Collector 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: Optional[Tuple[Callable, Callable]] = None, block_renderers: Optional[Tuple[Callable, Callable]] = 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。

参数

• catalog – catalog 的名称

• locale_dir – 消息 catalog 的基本路径

有关详细信息，请参见 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 – 事件的 arguments

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

在 3.1 版更改: 增加了 allowed_exceptions 来指定 path-through 异常

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

触发 event 并向回调函数传递 arguments。

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

参数

• event – 将被触发的事件的名称

• args – 事件的 arguments

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

0.5 新版功能.

在 3.1 版更改: 增加了 allowed_exceptions 来指定 path-through 异常

Sphinx 运行时信息

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

Sphinx.project

目标项目。查阅 Project。

Sphinx.srcdir

源目录

Sphinx.confdir

目录中存在 conf.py。

Sphinx.doctreedir

用于存储 pickle 文档树的目录。

Sphinx.outdir

用于存储构建文档的目录。

Sphinx 核心事件

这些事件都是众所周知的。将显示的参数提供给已注册的事件处理程序。用 Sphinx.connect() 在插件的 setup 函数中（注意 conf.py 也可以有 setup 函数）来连接事件处理程序。示例：

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)

下面是构建过程中发生的每个事件的概述。在下面的列表中，包括了事件的名称，它的回调参数，以及该事件的输入和输出类型：

1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)

for docname in docnames:
   5. event.env-purge-doc(app, env, docname)

   if doc changed and not removed:
      6. source-read(app, docname, source)
      7. run source parsers: text -> docutils.document
         - parsers can be added with the app.add_source_parser() API
      8. apply transforms based on priority: docutils.document -> docutils.document
         - event.doctree-read(app, doctree) is called in the middle of transforms,
           transforms come before/after this event depending on their priority.

9. event.env-merge-info(app, env, docnames, other)
   - if running in parallel mode, this event will be emitted for each process

10. event.env-updated(app, env)
11. event.env-get-updated(app, env)
12. event.env-check-consistency(app, env)

# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
# For builders that output a single page, they are first joined into a single doctree before post-transforms
# or the doctree-resolved event is emitted
for docname in updated-docs:
   13. apply post-transforms (by priority): docutils.document -> docutils.document
   14. event.doctree-resolved(app, doctree, docname)
       - In the event that any reference nodes fail to resolve, the following may emit:
       - event.missing-reference(env, node, contnode)
       - event.warn-missing-reference(domain, node)

15. Generate output files
16. event.build-finished(app, exception)

下面是这些事件的一个更详细的列表。

builder-inited(app)

在创建构建器对象时触发。它的名字是 app.builder。

config-inited(app, config)

当配置对象被初始化时触发。

1.8 新版功能.

env-get-outdated(app, env, added, changed, removed)

当环境确定哪些源文件已更改并应重新读取时触发。added， changed 和 removed 是环境决定的一组文档名。除此之外，你还可以返回一个文档名列表来重新阅读。

1.1 新版功能.

env-purge-doc(app, env, docname)

当应从环境中清除源文件的所有跟踪时发出，即源文件已被删除或在其被新读取之前发出。这适用于那些在环境属性中保留自己缓存的插件。

例如，环境中有所有模块的缓存。当源文件被更改时，缓存中的文件条目将被清除，因为模块声明可能已经从文件中删除了。

0.5 新版功能.

env-before-read-docs(app, env, docnames)

在环境确定了所有添加和更改的文件的列表之后，在读取它们之前发出。它允许插件作者在处理之前重新排序文档名列表（inplace），或者添加更多 Sphinx 没有考虑更改的文档名（但永远不要添加任何不在 env.found_docs 中的文档名）。

你也可以删除文档名称；这样做要小心，因为它会使 Sphinx 将更改的文件视为未更改的。

1.3 新版功能.

source-read(app, docname, source)

当读取源文件时触发。source 参数是列表，它的单个元素是源文件的内容。您可以处理内容并替换此项，以实现源代码级变换。

例如，如果你想使用 $ 符号来分隔内联数学，就像在 LaTeX 中一样，你可以使用正则表达式将 $...$ 替换为 :math:`...`。

0.5 新版功能.

object-description-transform(app, domain, objtype, contentnode)

当对象描述指令运行时触发。参数 domain 和 objtype 是字符串，指示对象的对象描述。而 contentnode 是对象的内容。它可以在适当的地方进行修改。

2.4 新版功能.

doctree-read(app, doctree)

当环境解析和读取了 doctree，并准备进行 pickle 时发出。doctree 可以就地修改。

missing-reference(app, env, node, contnode)

当无法解析对对象的交叉引用时触发。如果事件处理程序可以解析引用，它应该返回新的 docutils 节点，插入到文档树中的节点 node 的位置。通常这个节点是 reference 节点，其中包含子节点。如果处理程序不能解析交叉引用，它可以返回 None 让其他处理程序尝试，或者引发 NoUri 来阻止其他处理程序尝试，并抑制关于此交叉引用未解析的警告。

参数

• env – 构建环境（app.builder.env）。

• node – 要解析的 pending_xref 节点。它的属性 reftype、reftarget、modname 和 classname 决定了引用的类型和目标。

• contnode – 在将来引用中携带文本和格式的节点，应该是返回的引用节点的子节点。

0.5 新版功能.

warn-missing-reference(app, domain, node)

当对对象的交叉引用不能被解析时触发，即使在 missing-reference 之后。如果事件处理程序可以对丢失的引用发出警告，那么它应该返回 True。配置变量 nitpick_ignore 和 nitpick_ignore_regex 防止相应节点触发该事件。

3.4 新版功能.

doctree-resolved(app, doctree, docname)

当环境已经 “resolved” 文档树时触发，也就是说，所有的引用已经被解析并且 TOC 已经被插入。可以在适当的地方修改 doctree。

这里可以替换编写器中没有访问器方法的自定义节点，这样当编写器遇到这些方法时，它们就不会导致错误。

env-merge-info(app, env, docnames, other)

此事件仅在启用文档并行读取时触发。每次读取了一些文档的子流程都会触发一次。

您必须在将数据存储在自定义位置的环境中的扩展中处理此事件。否则，主进程中的环境将无法感知存储在子进程中的信息。

other 是来自子进程的环境对象，env 是来自主进程的环境对象。docnames 是在子进程中读取的一组文档名。

1.3 新版功能.

env-updated(app, env)

当构建环境的 update() 方法完成时触发，也就是说，环境和所有的文档树现在都是最新的。

你可以从处理器返回 docname 的可迭代对象。这些文件将被认为是更新的，并将在写作阶段（重新）编写。

0.5 新版功能.

在 1.3 版更改: 现在使用处理程序的返回值。

env-check-consistency(app, env)

当 Consistency 检查 phase 时触发。你可以检查整个文档的元数据的一致性。

1.6 新版功能: 作为 experimental 事件

html-collect-pages(app)

当 HTML 构建器开始编写非文档页面时触发。你可以通过从这个事件返回由 (pagename, context, templatename) 组成的可迭代对象来添加要写入的页面。

1.0 新版功能.

html-page-context(app, pagename, templatename, context, doctree)

当 HTML 构建器创建了一个上下文字典来呈现模板时触发——这可以用来向上下文添加自定义元素。

pagename 参数是所呈现页面的规范名称，也就是说，不带有 .html 后缀，并使用斜杠作为路径分隔符。templatename 是要渲染的模板的名称，这将是 'page.html' 用于 reST 文档中的所有页面。

context 参数是一个值字典，它被提供给模板引擎来呈现页面，并且可以修改为包含自定义值。key 一定是字符串。

当页面从 reST 文档创建时，doctree 参数将是 doctree；当仅从 HTML 模板创建页面时，它将是 None。

你可以从处理程序返回字符串，然后它将替换 'page.html' 作为这个页面的 HTML 模板。

备注

你可以安装 JS/CSS 文件的特定页面通过 Sphinx.add_js_file() 和 Sphinx.add_css_file() （ v3.5.0）。

0.4 新版功能.

在 1.3 版更改: 返回值现在可以指定模板名称。

linkcheck-process-uri(app, uri)

当 linkcheck 生成器从文档中收集超链接时触发。uri 是一个收集的 URI。事件处理器可以通过返回字符串来修改 URI。

4.1 新版功能.

build-finished(app, exception)

当构建完成时，Sphinx 退出之前发出，通常用于清理。此事件即使在构建过程引发异常（作为 exception 参数给出）时也会触发。事件处理程序运行后，在应用程序中重新引发该异常。如果构建过程没有引发异常，exception 将为 None。这允许根据异常状态定制清理操作。

0.5 新版功能.

检查 Sphinx 版本

使用它来调整您的插件以适应 Sphinx 中的 API 更改。

sphinx.version_info = (4, 4, 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] = {}, overrides: Dict[str, Any] = {})

配置文件的抽象。

配置对象使所有配置值的值作为属性可用。

它是通过 sphinx.application.Application.config 和 sphinx.environment.Environment.config 属性公开的。例如，要获取 language 的值，可以使用 app.config.language 或 env.config.language。

模板的桥梁

class sphinx.application.TemplateBridge

这个类定义了 “template bridge” 的接口，也就是说，一个类在给定模板名称和上下文的情况下呈现模板。

init(builder: Builder, theme: sphinx.theming.Theme = None, dirs: List[str] = 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 错误的基类。

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

鼓励插件从这个异常中派生自定义错误。

从 SphinxError 派生的异常 not 被视为意外，并显示给用户的一部分回溯（和完整的回溯保存在一个临时文件中）。

category

对异常的描述 “category”，用于将异常转换为字符串（”category: message”）。应该在子类中相应设置。

exception sphinx.errors.ConfigError

配置错误

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

异常错误

exception sphinx.errors.ThemeError

主题错误

exception sphinx.errors.VersionRequirementError

Sphinx 版本不兼容错误。