应用程序接口¶

每个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) 。

Added in version 1.0.

在 7.1 版本发生变更: 类型： version 现在允许 (major, minor) 形式。

Sphinx.connect(event: str, callback: Callable, priority: int = 500) → int[源代码]¶

寄存器回调什么时候打电话事件发射。

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

参数:

event -- 目标eve NT的名称
callback -- eve NT的回调函数
priority -- 回调的优先级。将按以下顺序调用回调 priority (升序)。

返回:

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

在 3.0 版本发生变更: 支持优先

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

注销回调者 listener_id .

参数:: listener_id -- 一个listener_id，它 connect() 退货

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

注册新的生成器。

参数:

builder -- 一个构建器类
override -- 如果为TRUE，则如果已安装同名的另一个构建器，则强制安装构建器eve n

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_config_value(name: str, default: Any, rebuild: Literal['', 'env', 'epub', 'gettext', 'html', 'applehelp', 'devhelp'], types: type | Collection[type] | ENUM = ()) → None[源代码]¶

注册配置值。

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

参数:

name -- 配置值的名称。建议使用扩展名作为前缀(例如 html_logo ， epub_title )
default -- 配置的默认值。
rebuild -- 重建的条件。它必须是以下值之一： * 'env' if a change in the setting only takes effect when a document is parsed -- this means that the whole environment must be rebuilt. * 'html' 如果更改设置需要完全重新生成HTML文档。* '' 如果更改设置将不需要任何特殊重建。
types -- 配置值的类型。可以指定类型列表。例如, [str] 用于描述接受字符串值的配置。

在 0.4 版本发生变更: 如果违约值是可调用的，它将以config对象作为参数进行调用，以获取默认值。这可用于实现其默认值依赖于其他值的配置值。

在 0.6 版本发生变更: 改变重建从一个简单的布尔值（相当于 '' 或 'env' ）到字符串。然而，布尔值仍然被接受并在内部转换。

Sphinx.add_event(name: str) → None[源代码]¶

注册调用的事件 name .

这是需要能够发射它。

参数:: name -- eve NT的名称

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

注册或重写docutils转换器类。

这用于注册自定义输出翻译器或替换内置翻译器。这允许扩展模块使用自定义翻译程序并为该翻译程序定义自定义节点(请参见 add_node() )。

参数:

name -- 翻译器的生成器的名称
translator_class -- 翻译员班
override -- 如果为TRUE，如果已经安装了同名的另一个转换器，则强制安装转换器eve n

Added in version 1.3.

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: tuple[Callable, Callable | None]) → None[源代码]¶

注册docutils节点类。

这对于docutils内部是必需的。它还可以在将来用于验证解析文档中的节点。

参数:

node -- 节点类
kwargs -- 每个构建器的访问函数(见下文)
override -- 如果为TRUE，如果已经安装了同名的另一个节点，则强制安装节点eve n

sphinx html、laxte、text和manpage编写器的节点访问者函数可以作为关键字参数提供：关键字应该是 'html' ， 'latex' ， 'text' ， 'man' ， 'texinfo' 或任何其他受支持的翻译器，值为 (visit, depart) 方法。 depart 可以是 None 如果 visit 功能提升 docutils.nodes.SkipNode . 例子：

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 -- 可枚举节点的类型。每个图形类型都有单独的编号序列。作为系统的图形类型， figure ， table 和 code-block 都是定义的。可以向这些默认地物类型添加自定义节点。如果给出了新的图形类型，也可以定义新的定制图形类型。
title_getter -- 获取节点标题的getter函数。它接受可枚举节点的实例，并且必须以字符串形式返回其标题。标题用于引用的默认标题 ref 。默认情况下，Sphinx搜索 docutils.nodes.caption 或 docutils.nodes.title 作为标题从节点中删除。
kwargs -- 每个构建器的访问者函数(与 add_node() )
override -- 如果为TRUE，如果已经安装了同名的另一个节点，则强制安装节点eve n

Added in version 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):
        ...

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

有关更多详细信息，请参阅 the Docutils docs 。

在 0.6 版本发生变更: 现在支持docutils 0.5样式的指令类。

自 1.8 版本弃用: 不推荐使用docutils 0.4样式（基于函数）指令支持。

在 1.8 版本发生变更: 添加覆盖关键字。

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

注册docutils角色。

参数:

name -- 角色名称
role -- 角色函数
override -- 如果为False，则如果已经安装了同名的另一个角色，则不要安装该角色。如果为True，则无条件安装该角色。

有关角色函数的更多详细信息，请参见 the Docutils docs 。

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_generic_role(name: str, nodeclass: Any, override: bool = False) → None[源代码]¶

注册通用docutils角色。

注册一个docutils角色，该角色只将其内容包装在 诺克勒斯 .

参数:: override -- 如果为False，则如果已经安装了同名的另一个角色，则不要安装该角色。如果为True，则无条件安装该角色。

Added in version 0.6.

在 1.8 版本发生变更: 添加覆盖关键字。

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

注册域。

参数:

domain -- 一个域类
override -- 如果为False，则如果另一个域已安装为相同名称，则不要安装它。如果为True，则无条件地安装域。

Added in version 1.0.

在 1.8 版本发生变更: 添加覆盖关键字。

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

在域中注册docutils指令。

喜欢 add_directive() ，但该指令被添加到名为域 .

参数:

domain -- 目标域的名称
name -- 指令的名称
cls -- 指令性类
override -- 如果为False，则如果已经安装了同名的另一个指令，则不要安装该指令。如果为True，则无条件地安装该指令。

Added in version 1.0.

在 1.8 版本发生变更: 添加覆盖关键字。

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

在域中注册docutils角色。

喜欢 add_role() ，但角色将添加到名为域 .

参数:

domain -- 目标域的名称
name -- 角色的名称
role -- 角色功能
override -- 如果为False，则如果已经安装了同名的另一个角色，则不要安装该角色。如果为True，则无条件安装该角色。

Added in version 1.0.

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_index_to_domain(domain: str, index: type[Index], override: bool = False) → None[源代码]¶

注册域的自定义索引。

添加自定义索引类初始化到名为的域域。

参数:

domain -- 目标域的名称
index -- 索引类
override -- 如果为False，则如果已经安装了同名的另一个索引，则不要安装该索引。如果为True，则无条件地安装该索引。

Added in version 1.0.

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable | None = None, ref_nodeclass: type[TextElement] | None = None, objname: str = '', doc_field_types: Sequence = (), override: bool = False) → None[源代码]¶

注册新的对象类型。

这种方法是添加新的 object 可以交叉引用的类型。它将做到：

创建新的指令（调用 直接命名 ）用于记录对象。它将自动添加索引项，如果 索引模板 不是空的；如果给定，则它必须正好包含 %s . 有关如何解释模板，请参见下面的示例。
创建新角色（调用 罗列名 ）交叉引用这些对象描述。
如果你提供 parse_node ，它必须是一个接受字符串和docutils节点的函数，并且必须用从字符串中解析的子元素填充该节点。然后，它必须返回要在交叉引用和索引项中使用的项的名称。见 conf.py 以本文档的源文件为例。
这个 对象名称 （如果没有给出，将默认为 直接命名 ）命名对象类型。它用于列出对象，例如在搜索结果中。

例如，如果在自定义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 如果你不想要进一步的文字装饰。如果文本应视为文本（例如，没有智能引号替换），但没有打字机样式，请使用 sphinx.addnodes.literal_emphasis 或 sphinx.addnodes.literal_strong .

对于角色内容，您具有与标准Sphinx角色相同的语法可能性（请参见交叉引用语法）

如果覆盖为True，则即使已安装具有相同名称的对象_类型，也会强制安装给定的对象类型。

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[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 版本发生变更: 添加覆盖关键字。

Sphinx.add_transform(transform: type[Transform]) → None[源代码]¶

注册要在解析后应用的docutils转换。

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

参数:: transform -- 转换类

Sphinx变换的优先级范围类别¶
优先	Sphinx的主要用途
0－99	通过docutils修复无效节点。翻译病历。
100-99	制备
300～399	早期的
400～699	主要的
700—799	后期处理。修改文本和引用的最后期限。
800～899	收集引用和引用的节点。域处理。
900-99	完成并清理。

参考文献： 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`

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

Added in version 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`

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

Added in version 1.0.

在 1.6 版本发生变更: 任选 alternate and/or title attributes can be supplied with the arguments alternate (a Boolean) and title (a string). The default is no title and alternate = False. For more information, refer to the documentation 。

在 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}

Added in version 1.3.

Added in version 3.1: after_hyperref 选择权。

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

为源代码注册新的lexer。

使用 莱克塞 用给定语言突出显示代码块别名 .

Added in version 0.6.

在 2.1 版本发生变更: 将lexer类作为参数。

在 4.0 版本发生变更: 删除了对词法分析器实例作为参数的支持。

Sphinx.add_autodocumenter(cls: Any, override: bool = False) → None[源代码]¶

为AutoDoc扩展注册一个新的文档管理器类。

增列 cls 作为新的文档生成器类 sphinx.ext.autodoc 分机。它必须是的子类 sphinx.ext.autodoc.Documenter 。这允许自动记录新类型的对象。有关如何子类化的示例，请参阅AutoDoc模块的源代码 Documenter 。

如果覆盖是真的，给定的 cls 强制安装，即使已安装同名的文档管理器。

看见为IntEnum开发AutoDoc扩展。

Added in version 0.6.

在 2.2 版本发生变更: 添加覆盖关键字。

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

注册一个新的 getattr -类似于AutoDoc扩展的功能。

添加 吸气剂 ，它必须是具有与 getattr() 内置，作为作为作为对象实例的autoDoc属性getter typ . 所有需要AutoDoc获取类型属性的情况都将由该函数处理，而不是 getattr() .

Added in version 0.6.

Sphinx.add_search_language(cls: Any) → None[源代码]¶

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

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

Added in version 1.1.

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

注册源文件的后缀。

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

参数:: override -- 如果为FALSE，则不要安装已安装的相同后缀。如果为True，则无条件安装后缀。

Added in version 1.8.

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

注册分析器类。

参数:: override -- 如果为False，则如果已经为相同后缀安装了另一个解析器，则不要安装它。如果为True，则无条件安装解析器。

Added in version 1.4.

在 1.8 版本发生变更: 后缀参数已弃用。它只接受 语法分析器 争论。使用 add_source_suffix() API注册后缀。

在 1.8 版本发生变更: 添加覆盖关键字。

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None[源代码]¶

注册环境收集器类。

参照环境收集器API .

Added in version 1.6.

Sphinx.add_html_theme(name: str, theme_path: str) → None[源代码]¶

注册HTML主题。

这个 name 是一个主题名称，并且 theme_path 是主题的完整路径(参考：将主题作为python包分发 )。

Added in version 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() 有关详细信息。

Added in version 1.8.

Sphinx.add_message_catalog(catalog: str, locale_dir: str) → None[源代码]¶

注册消息目录。

参数:

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

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

Added in version 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 -- 回调中允许的异常列表

Added in version 0.5.

在 3.1 版本发生变更: 增列 allowed_exceptions 指定直通路径例外

Sphinx运行时信息¶

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

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

Sphinx.srcdir¶: 源目录。

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

Sphinx.doctreedir¶: 存储腌制doctrees的目录。

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)¶: 在初始化配置对象时发出。

Added in version 1.8.

env-get-outdated(app, env, added, changed, removed)¶: 当环境确定哪些源文件已更改并应重新读取时发出。补充，改变和 远离的 是环境确定的文档名集。除此之外，您还可以返回一个要重新读取的文档名列表。

Added in version 1.1.

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

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

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

Added in version 0.5.

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

在环境确定所有添加和更改的文件的列表后，以及在读取这些文件之前发出。它允许扩展作者对文档名列表重新排序（原地）在处理之前，或添加更多Sphinx认为未更改的文档名（但不要添加任何不在 env.found_docs ）

您还可以删除文档名；请小心执行此操作，因为这样会使Sphinx将更改的文件视为不变的。

Added in version 1.3.

source-read(app, docname, source)¶

在读取源文件时发出。这个来源参数是一个列表，其单个元素是源文件的内容。您可以处理内容并替换此项以实现源代码级转换。

例如，如果要使用 $ 用于分隔内联数学的符号，如在LaTex中，可以使用正则表达式替换 $...$ 通过 :math:`... '.

Added in version 0.5.

include-read(app, relative_path, parent_docname, content)¶: 方法读取文件时激发 include 指令。这个 relative_path 参数是一个 Path 对象，该对象表示包含的文件从 source directory 。这个 parent_docname 参数是包含 include 指令。这个 source 参数是一个列表，其单个元素是所包含文件的内容。您可以处理内容并替换该项以转换包含的内容，就像使用 source-read 事件。

Added in version 7.2.5.

参见

这个 include 指令和 source-read 事件。

object-description-transform(app, domain, objtype, contentnode)¶: 当对象描述指令运行时发出。这个域和 对象类型 参数是表示对象描述的字符串。以及 内容节点 是对象的内容。可以就地修改。

Added in version 2.4.

doctree-read(app, doctree)¶: 当doctree已被环境解析和读取，并且即将被酸洗时发出。这个 文档树 可以就地修改。

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

当无法解析对对象的交叉引用时激发。如果事件处理程序可以解析引用，则它应该返回一个新的Docutils节点，该节点将被插入到文档树中来代替该节点 node 。通常，此节点是 reference 包含以下内容的节点 contnode 作为一个孩子。如果处理程序无法解析交叉引用，它可以返回 None 让其他处理程序尝试或引发 NoUri 以防止其他处理程序尝试并取消有关此交叉引用未解析的警告。

参数:

env -- 构建环境 (app.builder.env ）
node -- 这个 pending_xref 要解析的节点。它的 reftype ， reftarget ， modname 和 classname 属性确定引用的类型和目标。
contnode -- 在将来的引用中承载文本和格式的节点，它应该是返回的引用节点的子节点。

Added in version 0.5.

warn-missing-reference(app, domain, node)¶: 当无法解析对对象的交叉引用时激发 missing-reference 。如果事件处理程序可以对缺少的引用发出警告，则它应该返回 True 。配置变量 nitpick_ignore 和 nitpick_ignore_regex 防止为相应节点发出事件。

Added in version 3.4.

doctree-resolved(app, doctree, docname)¶

当一个doctree被环境“解析”时，即所有引用都被解析并插入了TOC时发出。这个 文档树 可以就地修改。

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

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

此事件仅在启用并行读取文档时发出。对于已读取某些文档的每个子流程，它都会发出一次。

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

其他是子进程中的环境对象， env 是从环境的主要过程。 文档名称 是在子进程中读取的一组文档名。

Added in version 1.3.

env-updated(app, env)¶

当环境和所有文档树现在都是最新的时，在读取所有文档后发出。

您可以从处理程序返回一个iterable of docname。这些文件将被认为是更新的，并将在写作阶段被（重新）书写。

Added in version 0.5.

在 1.3 版本发生变更: 现在使用处理程序的返回值。

env-check-consistency(app, env)¶: 在一致性检查阶段发出。您可以检查整个文档的元数据的一致性。

Added in version 1.6: 作为一个 实验的 事件

html-collect-pages(app)¶: 当HTML生成器开始写入非文档页时发出。您可以通过从此事件返回一个iterable来添加要写入的页面，该iterable包含 (pagename, context, templatename) .

Added in version 1.0.

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

当HTML生成器创建了一个上下文词典以呈现模板时发出--这可用于向上下文添加自定义元素。

这个 页面名称 参数是正在呈现的页面的规范名称，即 .html 后缀和使用斜线作为路径分隔符。这个 模板名 是要呈现的模板的名称，这将是 'page.html' 其他文档的所有页面。

这个语境参数是提供给模板引擎以呈现页面的值的字典，可以修改为包含自定义值。键必须是字符串。

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

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

备注

您可以通过以下方式安装特定页面的JS/CSS文件 Sphinx.add_js_file() 和 Sphinx.add_css_file() 从3.5.0版开始。

Added in version 0.4.

在 1.3 版本发生变更: 返回值现在可以指定模板名称。

linkcheck-process-uri(app, uri)¶: 当LinkCheck生成器从文档收集超链接时激发。 uri 是一个收集的URI。事件处理程序可以通过返回字符串来修改URI。

Added in version 4.1.

build-finished(app, exception)¶: 在Sphinx退出之前，当建筑完成时发出，通常用于清理。即使生成进程引发异常，也会发出此事件，该异常作为例外争论。在事件处理程序运行后，将在应用程序中重新引发异常。如果生成过程没有引发异常，例外将 None . 这允许根据异常状态自定义清理操作。

Added in version 0.5.

检查Sphinx版本¶

使用它来调整您对sphinx中API更改的扩展。

sphinx.version_info = (7, 3, 0, 'beta', 0)¶

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

一个由五个元素组成的元组；对于Sphinx 1.2.1 Beta 3版，这将是 (1, 2, 1, 'beta', 3) . 第四个元素可以是： alpha ， beta ， rc ， final . final 始终将0作为最后一个元素。

Added in version 1.2: 在版本1.2之前，请检查字符串 sphinx.__version__ .

配置对象¶

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

配置文件抽象。

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

它是通过 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 .

主题是一个 sphinx.theming.Theme 反对或不反对；在后一种情况下， 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将中止构建并向用户显示异常类别和消息。

对于自定义错误，鼓励从该异常派生扩展。

例外情况 not 来源 SphinxError 将被视为意外事件，并显示给用户，其中一部分回溯（完整的回溯保存在临时文件中）。

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

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

On this page

Site navigation

应用程序接口¶

扩展设置¶

发射事件¶

Sphinx运行时信息¶

Sphinx核心事件¶

检查Sphinx版本¶

配置对象¶

模板桥¶

例外情况¶