事件管理器 API

class sphinx.events.EventManager(app: Sphinx)[source]

Sphinx 的事件管理器。

add(name: str) → None[source]

注册一个名为 name 的自定义 Sphinx 事件。

这是发出事件所必需的。

参数:

name – 事件的名称。

connect(name: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int) → int[source]
connect(name: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int) → int
connect(name: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int) → int
connect(name: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int) → int
connect(name: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int) → int
connect(name: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int) → int
connect(name: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int) → int
connect(name: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int) → int
connect(name: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int) → int
connect(name: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int) → int
connect(name: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int) → int
connect(name: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int) → int
connect(name: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int) → int
connect(name: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int) → int
connect(name: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int) → int
connect(name: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int) → int
connect(name: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int) → int
connect(name: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int) → int
connect(name: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int) → int
connect(name: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int) → int
connect(name: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int) → int
connect(name: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int) → int
connect(name: Literal['autodoc-before-process-signature'], callback: _AutodocBeforeProcessSignatureListener, priority: int) → int
connect(name: Literal['autodoc-process-signature'], callback: _AutodocProcessSignatureListener, priority: int) → int
connect(name: Literal['autodoc-process-bases'], callback: _AutodocProcessBasesListener, priority: int) → int
connect(name: Literal['autodoc-skip-member'], callback: _AutodocSkipMemberListener, priority: int) → int
connect(name: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int) → int
connect(name: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int) → int
connect(name: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int) → int
connect(name: str, callback: Callable[..., Any], priority: int) → int

将处理程序连接到特定事件。

注册 callback 以在发出 name 事件时被调用。

有关可用的核心事件及其相应回调函数的参数的详细信息，请参阅 事件回调。

参数:

  • name – 目标事件的名称。

  • callback – 事件的回调函数。

  • priority – 回调的优先级。回调将按 priority 的升序调用。

返回:

一个侦听器 ID，用于 disconnect() 方法。

3.0 版中已更改: 支持 priority

disconnect(listener_id: int) → None[source]

断开由 listener_id 指定的处理程序。

参数:

listener_id – 之前由 connect() 返回的侦听器 ID。

emit(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[Any][source]

发出一个 Sphinx 事件。

这会发出 name 事件并将 args 传递给处理程序函数。返回所有处理程序的返回值作为列表。不要在扩展中发出核心 Sphinx 事件！

参数:

  • name – 将要发出的事件的名称。

  • args – 事件的参数，将传递给处理程序函数。

  • allowed_exceptions – 处理程序中允许的异常列表。

3.1 版中已更改: 添加了 allowed_exceptions 以指定直通异常

emit_firstresult(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any[source]

发出一个 Sphinx 事件并返回第一个结果。

这会发出 name 事件并将 args 传递给处理程序函数。返回第一个非 None 的结果。

参数:

  • name – 将要发出的事件的名称。

  • args – 事件的参数，将传递给处理程序函数。

  • allowed_exceptions – 处理程序中允许的异常列表。

版本 0.5 中新增。

3.1 版中已更改: 添加了 allowed_exceptions 以指定直通异常