事件回调API

将回调函数连接到事件是一种扩展Sphinx的简单方法，可以在各个点上钩住构建过程。

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

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

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

参见

扩展可以使用 Sphinx.add_event() 添加自己的事件，并使用 EventManager.emit() 或 EventManager.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(app, env, node, contnode)
       - event.warn-missing-reference(app, 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] with a single element, representing the content of the source file.

当读取源文件时发出。

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

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

在 0.5 版本加入.

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

参数:

• app -- Sphinx

• relative_path -- Path，表示相对于 source directory 的包含文件。

• 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 可以就地修改。

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

参数:

• app -- Sphinx

• env -- BuildEnvironment

• node -- The 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

当环境已“解析”文档树时发出，也就是说，已解析所有引用并插入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

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

您可以从处理程序返回可迭代的文档名。这些文件将被视为更新，并将在编写阶段（重新）编写。

在 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生成器创建了用于呈现模板的上下文字典时发出——这可用于向上下文添加自定义元素。

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

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

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

您可以从处理程序返回一个字符串，然后它将替换“`”页面.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 版本加入.

Previous

应用接口

Next

项目接口