Event callbacks API

Connecting callback functions to events is a simple way to extend Sphinx, by hooking into the build process at various points.

Use Sphinx.connect() in an extension's setup function, or a setup function in your project's conf.py, to connect functions to the events:

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

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

参考

Extensions can add their own events by using Sphinx.add_event(), and calling them them with EventManager.emit() or EventManager.emit_firstresult().

Core events overview

Below is an overview of the core event that happens during a build.

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)

Here is also a flow diagram of the events, within the context of the Sphinx build process:

Sphinx core events flow

Core event details

Here is a more detailed list of these events.

config-inited(app, config)

パラメータ:

• app -- Sphinx

• config -- Config

Emitted when the config object has been initialized.

Added in version 1.8.

builder-inited(app)

パラメータ:

app -- Sphinx

Emitted when the builder object has been created (available as app.builder).

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

パラメータ:

• app -- Sphinx

• env -- BuildEnvironment

• added -- Set[str]

• changed -- Set[str]

• removed -- Set[str]

Returns:

Sequence[str] of additional docnames to re-read

Emitted when the environment determines which source files have changed and should be re-read. added, changed and removed are sets of docnames that the environment has determined. You can return a list of docnames to re-read in addition to these.

Added in version 1.1.

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

パラメータ:

• app -- Sphinx

• env -- BuildEnvironment

• docname -- str

Emitted when all traces of a source file should be cleaned from the environment, that is, if the source file is removed or before it is freshly read. This is for extensions that keep their own caches in attributes of the environment.

For example, there is a cache of all modules on the environment. When a source file has been changed, the cache's entries for the file are cleared, since the module declarations could have been removed from the file.

Added in version 0.5.

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

パラメータ:

• app -- Sphinx

• env -- BuildEnvironment

• docnames -- list[str]

Emitted after the environment has determined the list of all added and changed files and just before it reads them. It allows extension authors to reorder the list of docnames (inplace) before processing, or add more docnames that Sphinx did not consider changed (but never add any docnames that are not in found_docs).

イベントハンドラはドキュメント名をリストから削除することもできます; 注意深くこの方法を利用することで、Sphinxに変更済みのファイルを未変更であるとして扱わせることができます。

Added in version 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.

Emitted when a source file has been read.

You can process the content and replace this item to implement source-level transformations.

もしも、LaTeXと同じように、 $ 記号を、インラインの数式の区切り文字にしたい場合には、このイベントハンドラの中で、正規表現を使用して $...$ を :math:`...` に置き換えることで実現できます。

Added in version 0.5.

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

パラメータ:

• app -- Sphinx

• relative_path -- Path representing the included file relative to the source directory.

• parent_docname -- str of the document name that contains the include directive.

• content -- list[str] with a single element, representing the content of the included file.

Emitted when a file has been read with the include directive.

You can process the content and replace this item to transform the included content, as with the source-read event.

Added in version 7.2.5.

参考

The include directive and the source-read event.

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

パラメータ:

• app -- Sphinx

• domain -- str

• objtype -- str

• contentnode -- desc_content

Emitted when an object description directive has run. The domain and objtype arguments are strings indicating object description of the object. And contentnode is a content for the object. It can be modified in-place.

Added in version 2.4.

doctree-read(app, doctree)

パラメータ:

• app -- Sphinx

• doctree -- docutils.nodes.document

Emitted when a doctree has been parsed and read by the environment, and is about to be pickled. The doctree can be modified in-place.

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

パラメータ:

• app -- Sphinx

• env -- BuildEnvironment

• node -- The pending_xref node to be resolved. Its reftype, reftarget, modname and classname attributes determine the type and target of the reference.

• contnode -- このノードは、将来の参照が持つ、テキストとフォーマット情報を持ちます。これは返される参照ノードの子供にならなければなりません。

Returns:

A new node to be inserted in the document tree in place of the node, or None to let other handlers try.

Emitted when a cross-reference to an object cannot be resolved. If the event handler can resolve the reference, it should return a new docutils node to be inserted in the document tree in place of the node node. Usually this node is a reference node containing contnode as a child. If the handler can not resolve the cross-reference, it can either return None to let other handlers try, or raise NoUri to prevent other handlers in trying and suppress a warning about this cross-reference being unresolved.

Added in version 0.5.

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

パラメータ:

• app -- Sphinx

• domain -- The Domain of the missing reference.

• node -- The pending_xref node that could not be resolved.

Returns:

True if a warning was emitted, else None

Emitted when a cross-reference to an object cannot be resolved even after missing-reference. If the event handler can emit warnings for the missing reference, it should return True. The configuration variables nitpick_ignore and nitpick_ignore_regex prevent the event from being emitted for the corresponding nodes.

Added in version 3.4.

doctree-resolved(app, doctree, docname)

パラメータ:

• app -- Sphinx

• doctree -- docutils.nodes.document

• docname -- str

環境がdoctreeに関して"resolved(解決)"と判断したときに発行されます。これは、すべての参照が解決され、目次が挿入された時、ということになります。 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

Returns:

iterable of str

Emitted after reading all documents, when the environment and all doctrees are now up-to-date.

イベントハンドラより、ドキュメント名のイテレータを返すことができます。これらのドキュメントはアップデートされたとみなされ、書き込みフェイズにて新規書き込み(または書き換え)が行われます。

Added in version 0.5.

バージョン 1.3 で変更: イベントハンドラからの戻り値が利用されるようになりました。

env-get-updated(app, env)

パラメータ:

• app -- Sphinx

• env -- BuildEnvironment

Returns:

iterable of str

Emitted when the environment determines which source files have changed and should be re-read. You can return an iterable of docnames to re-read.

env-check-consistency(app, env)

パラメータ:

• app -- Sphinx

• env -- BuildEnvironment

Emitted when Consistency checks phase. You can check consistency of metadata for whole of documents.

Added in version 1.6.

write-started(app, builder)

パラメータ:

• app -- Sphinx

• builder -- Builder

Emitted before the builder starts to resolve and write documents.

Added in version 7.4.

build-finished(app, exception)

パラメータ:

• app -- Sphinx

• exception -- Exception or None

ビルドが完了し、Sphinxが終了する際に発行されます。通常はクリーンアップに使用されます。このイベントは、ビルドプロセスが例外を上げたときにも発行されます。その場合には、 exception 引数が渡されます。アプリケーションの中で発生した例外は、このイベントハンドラが終了した段階で、再度投げられます。もしもビルドプロセスが例外を発生しなかった場合には、 exception は None になります。これによって、例外の種類ごとの、クリーンアップの処理をカスタム化できます。

Added in version 0.5.

Builder specific events

These events are emitted by specific builders.

html-collect-pages(app)

パラメータ:

app -- Sphinx

Returns:

iterable of (pagename, context, templatename) where pagename and templatename are strings and context is a dict[str, Any].

Emitted when the HTML builder is starting to write non-document pages.

You can add pages to write by returning an iterable from this event.

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 or None

Returns:

str or None

HTMLビルダーがコンテキストの辞書を作り、テンプレートを使用してレンダリングを行う時に発行されます。このイベントは、追加のカスタムの要素をコンテキストに追加する場合に使用できます。

The pagename argument is the canonical name of the page being rendered, that is, without .html suffix and using slashes as path separators. The templatename is the name of the template to render, this will be 'page.html' for all pages from reStructuredText documents.

The context argument is a dictionary of values that are given to the template engine to render the page and can be modified to include custom values.

The doctree argument will be a doctree when the page is created from a reStructuredText documents; it will be None when the page is created from an HTML template alone.

イベントハンドラは文字列を返すことができます、この文字列は 'page.html' に代わりHTMLテンプレートとして、このページのレンダリングに利用されるテンプレート名になります。

Tip

You can install JS/CSS files for the specific page via Sphinx.add_js_file() and Sphinx.add_css_file() (since v3.5.0).

Added in version 0.4.

バージョン 1.3 で変更: 戻り値により使用するテンプレート名を指定できるようになりました。

linkcheck-process-uri(app, uri)

パラメータ:

• app -- Sphinx

• uri -- str of the collected URI

Returns:

str or None

Emitted when the linkcheck builder collects hyperlinks from document.

The event handlers can modify the URI by returning a string.

Added in version 4.1.

Previous

アプリケーションAPI

Next

プロジェクト API