事件回调 API

将回调函数连接到事件是扩展 Sphinx 的一种简单方法，通过在各个点Hook到构建过程中。

在扩展的 setup 函数或项目的 conf.py 中的 setup 函数中使用 Sphinx.connect()，将函数连接到事件

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

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

另请参阅

扩展可以通过使用 Sphinx.add_event() 添加它们自己的事件，并使用 Sphinx.emit() 或 Sphinx.emit_firstresult() 调用它们。

核心事件概述

以下是构建期间发生的核心事件的概述。

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
         - event.include-read(app, relative_path, parent_docname, content)
           is called for each include directive
      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)

if environment is written to disk:
   12. event.env-check-consistency(app, env)

13. event.write-started(app, builder)
    - This is called after ``app.parallel_ok`` has been set,
      which must not be altered by any event handler.

# 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:
   14. apply post-transforms (by priority): docutils.document -> docutils.document
   15. 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)

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

这里还有一个事件流程图，在 Sphinx 构建过程的上下文中

Sphinx 核心事件流程

核心事件详情

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

config-inited(app, config)

参数:

• app – Sphinx

• config – Config

当配置对象已初始化时发出。

在版本 1.8 中添加。

builder-inited(app)

参数:

app – Sphinx

当构建器对象已创建时发出（可用作 app.builder）。

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

参数:

• app – Sphinx

• env – BuildEnvironment

• added – Set[str]

• changed – Set[str]

• removed – Set[str]

返回:

Sequence[str] 要重新读取的额外文档名

当环境确定哪些源文件已更改并且应该重新读取时发出。 added、 changed 和 removed 是环境已确定的文档名集合。 您可以返回要重新读取的文档名列表，以补充这些文档名。

在版本 1.1 中添加。

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

参数:

• app – Sphinx

• env – BuildEnvironment

• docname – str

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

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

在版本 0.5 中添加。

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

参数:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

在环境确定所有已添加和已更改文件的列表之后，以及在读取它们之前发出。 它允许扩展作者在处理之前对文档名列表进行重新排序（就地），或者添加 Sphinx 未考虑更改的更多文档名（但永远不要添加 found_docs 中不存在的任何文档名）。

您也可以删除文档名称； 谨慎执行此操作，因为它会使 Sphinx 将更改的文件视为未更改。

在版本 1.3 中添加。

source-read(app, docname, content)

参数:

• app – Sphinx

• docname – str

• content – list[str]，包含单个元素，表示包含文件的内容。

当源文件已被读取时发出。

您可以处理 content 并替换此项以实现源级别的转换。

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

在版本 0.5 中添加。

include-read(app, relative_path, parent_docname, content)

参数:

• app – Sphinx

• relative_path – Path，表示包含的文件相对于 源目录。

• parent_docname – 包含 include 指令的文档名称的 str。

• content – list[str]，包含单个元素，表示包含文件的内容。

当使用 include 指令读取文件时发出。

您可以处理 content 并替换此项以转换包含的内容，就像 source-read 事件一样。

在版本 7.2.5 中添加。

另请参阅

include 指令和 source-read 事件。

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

参数:

• app – Sphinx

• domain – str

• objtype – str

• contentnode – desc_content

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

在版本 2.4 中添加。

doctree-read(app, doctree)

参数:

• app – Sphinx

• doctree – docutils.nodes.document

当 doctree 已被环境解析和读取，并且即将被 pickle 化时发出。 doctree 可以就地修改。

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

参数:

• app – Sphinx

• env – BuildEnvironment

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

• contnode – 节点，用于携带未来引用内的文本和格式，并且应该是返回的引用节点的子节点。

返回:

要插入到文档树中以代替节点的新节点，或者 None 以便其他处理程序尝试。

当无法解析对对象的交叉引用时发出。 如果事件处理程序可以解析引用，则它应返回一个新的 docutils 节点，以插入到文档树中以代替节点 node。 通常，此节点是包含 contnode 作为子节点的 reference 节点。 如果处理程序无法解析交叉引用，则它可以返回 None 以便其他处理程序尝试，或者引发 NoUri 以阻止其他处理程序尝试，并抑制有关此交叉引用未解析的警告。

在版本 0.5 中添加。

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

参数:

• app – Sphinx

• domain – 丢失引用的 Domain。

• node – 无法解析的 pending_xref 节点。

返回:

如果发出警告，则为 True，否则为 None

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

在版本 3.4 中添加。

doctree-resolved(app, doctree, docname)

参数:

• app – Sphinx

• doctree – docutils.nodes.document

• docname – str

当 doctree 已被环境“解析”时发出，即，所有引用都已解析，并且 TOC 都已插入。 doctree 可以就地修改。

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

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

参数:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

• other – BuildEnvironment

仅当启用文档的并行读取时，才会发出此事件。 对于每个读取了一些文档的子进程，它都会发出一次。

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

other 是来自子进程的环境对象，env 是来自主进程的环境。 docnames 是子进程中已读取的文档名称集合。

在版本 1.3 中添加。

env-updated(app, env)

参数:

• app – Sphinx

• env – BuildEnvironment

返回:

可迭代的 str

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

您可以从处理程序返回文档名的可迭代对象。 然后，这些文档将被视为已更新，并且将在写入阶段（重新）写入。

在版本 0.5 中添加。

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

env-get-updated(app, env)

参数:

• app – Sphinx

• env – BuildEnvironment

返回:

可迭代的 str

当环境确定哪些源文件已更改并且应该重新读取时发出。 您可以返回要重新读取的文档名的可迭代对象。

env-check-consistency(app, env)

参数:

• app – Sphinx

• env – BuildEnvironment

当一致性检查阶段时发出。 您可以检查整个文档的元数据的一致性。

在版本 1.6 中添加。

write-started(app, builder)

参数:

• app – Sphinx

• builder – Builder

在构建器开始解析和写入文档之前发出。

在版本 7.4 中添加。

build-finished(app, exception)

参数:

• app – Sphinx

• exception – Exception 或 None

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

在版本 0.5 中添加。

构建器特定事件

这些事件由特定的构建器发出。

html-collect-pages(app)

参数:

app – Sphinx

返回:

可迭代的 (pagename, context, templatename)，其中 pagename 和 templatename 是字符串，context 是 dict[str, Any]。

当 HTML 构建器开始写入非文档页面时发出。

您可以通过从此事件返回一个可迭代对象来添加要写入的页面。

在版本 1.0 中添加。

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

参数:

• app – Sphinx

• pagename – str

• templatename – str

• context – dict[str, Any]

• doctree – docutils.nodes.document 或 None

返回:

str 或 None

当 HTML 构建器创建用于呈现模板的上下文字典时发出 – 这可用于向上下文添加自定义元素。

pagename 参数是要呈现页面的规范名称，即，没有 .html 后缀并使用斜杠作为路径分隔符。 templatename 是要呈现的模板的名称，对于来自 reStructuredText 文档的所有页面，这将是 'page.html'。

context 参数是值字典，这些值被提供给模板引擎以呈现页面，并且可以修改为包含自定义值。

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

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

提示

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

在版本 0.4 中添加。

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

linkcheck-process-uri(app, uri)

参数:

• app – Sphinx

• uri – 从文档收集的 URI 的 str

返回:

str 或 None

当 linkcheck 构建器从文档收集超链接时发出。

事件处理程序可以通过返回字符串来修改 URI。

在版本 4.1 中添加。

上一个

应用程序 API

下一个

项目 API