事件回调API

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

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

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(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

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

Added in version 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 是环境确定的文档名集合。除了这些，你还可以返回一个要重读的文档名列表。

Added in version 1.1.

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

参数:

• app -- Sphinx

• env -- BuildEnvironment

• docname -- str

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

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

Added in version 0.5.

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

参数:

• app -- Sphinx

• env -- BuildEnvironment

• docnames -- list[str]

在环境确定所有添加和更改的文件的列表后以及在读取它们之前发布。它允许扩展作者重新排序文档名列表（ inplace ），或者添加更多Sphinx认为没有更改的文档名（但永远不要添加任何不在中的文档名 found_docs ).

您还可以删除文档名称;请谨慎执行，因为这会使Sphinx将更改的文件视为未更改的文件。

Added in version 1.3.

source-read(app, docname, content)

参数:

• app -- Sphinx

• docname -- str

• content -- list[str] 具有单个元素，代表所包含文件的内容。

当读取源文件时发出。

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

例如，如果您想使用 $ 符号来分隔内联数学，就像在LaTeX中一样，您可以使用正规表达来替换 $...$ 通过 :math:`... `.

Added in version 0.5.

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

参数:

• app -- Sphinx

• relative_path -- Path 表示相对于 source directory .

• parent_docname -- str 包含 include 指令。

• content -- list[str] 具有单个元素，代表所包含文件的内容。

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

您可以处理 content 并替换此项以转换包含的内容，就像 source-read 活动

Added in version 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 是对象的内容。 它可以就地修改。

Added in version 2.4.

doctree-read(app, doctree)

参数:

• app -- Sphinx

• doctree -- docutils.nodes.document

当环境已解析和读取文档树并且即将被pickle时弹出。的 doctree 可以就地修改。

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

参数:

• app -- Sphinx

• env -- BuildEnvironment

• node -- 的 pending_xref 节点需要解决。其 reftype , reftarget , modname 和 classname 属性确定引用的类型和目标。

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

返回:

将新节点插入文档树中以取代该节点，或者 None 让其他处理者尝试。

当无法解析对象的交叉引用时引发。如果事件处理程序可以解析引用，则它应该返回一个新的docutils节点，以取代该节点插入到文档树中 node . 通常这个节点是 reference 节点的包括 contnode 小时候。如果处理程序无法解析交叉引用，则可以返回 None 让其他处理者尝试或提出 NoUri 以防止其他处理程序尝试，并抑制有关此交叉引用未解决的警告。

Added in version 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 防止事件为相应的节点发出。

Added in version 3.4.

doctree-resolved(app, doctree, docname)

参数:

• app -- Sphinx

• doctree -- docutils.nodes.document

• docname -- str

当环境“解析”文档树时，即所有引用都已解析并插入了目录时，会弹出。 的 doctree 可以就地修改。

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

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

参数:

• app -- Sphinx

• env -- BuildEnvironment

• docnames -- list[str]

• other -- BuildEnvironment

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

您必须在将数据存储在环境中的自定义位置的扩展中处理此事件。 否则，主流程中的环境将不会意识到子流程中存储的信息。

other 是子流程中的环境对象， env 是从主过程开始的环境。 docnames 是子流程中已读取的一组文档名称。

Added in version 1.3.

env-updated(app, env)

参数:

• app -- Sphinx

• env -- BuildEnvironment

返回:

可迭代的 str

在阅读所有文档后，当环境和所有文档树现已更新时发出。

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

Added in version 0.5.

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

env-get-updated(app, env)

参数:

• app -- Sphinx

• env -- BuildEnvironment

返回:

可迭代的 str

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

env-check-consistency(app, env)

参数:

• app -- Sphinx

• env -- BuildEnvironment

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

Added in version 1.6.

write-started(app, builder)

参数:

• app -- Sphinx

• builder -- Builder

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

Added in version 7.4.

build-finished(app, exception)

参数:

• app -- Sphinx

• exception -- Exception 或 None

当构建完成时、Sphinx退出之前发射，通常用于清理。 即使生成过程引发异常（给定为 exception 论点 事件处理程序运行后，该异常将在应用程序中重新引发。 如果构建过程没有出现异常， exception 将 None . 这允许根据异常状态自定义清理操作。

Added in version 0.5.

生成器特定事件

这些事件由特定的生成器发出。

html-collect-pages(app)

参数:

app -- Sphinx

返回:

可迭代的 (pagename, context, templatename) 哪里 pagename 和 templatename 是弦和 context 是一 dict[str, Any] .

当HTML生成器开始编写非文档页面时发出。

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

Added in version 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 是要渲染的模板的名称，这将是 'page.html' reStructuredText文档中的所有页面。

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

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

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

小技巧

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

Added in version 0.4.

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

linkcheck-process-uri(app, uri)

参数:

• app -- Sphinx

• uri -- str 收集的URI的

返回:

str 或 None

当链接检查生成器从文档收集超链接时弹出。

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

Added in version 4.1.

Previous

应用程序API

Next

项目API