事件管理器API

class sphinx.events.EventManager(app: Sphinx)[源代码]

Sphinx的活动管理器

add(name: str) → None[源代码]

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

需要这样做才能发出该事件。

参数:

name -- 事件的名称。

connect(name: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int) → int[源代码]
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 事件时调用。

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

参数:

  • name -- 目标事件的名称。

  • callback -- 事件的回调函数。

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

返回:

监听器ID，用于 disconnect() 方法。

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

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

断开由 listener_id 给出的处理程序。

参数:

listener_id -- 先前由 connect() 返回的 listener_id。

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

发射Sphinx事件。

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

参数:

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

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

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

在 3.1 版本发生变更: 添加了*allowed_exceptions*来指定路径穿越异常

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

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

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

参数:

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

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

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

在 0.5 版本加入.

在 3.1 版本发生变更: 添加了*allowed_exceptions*来指定路径穿越异常