イベントコールバックAPI

コールバック関数をイベントに接続することは、さまざまなポイントでビルドプロセスにフックすることで、Sphinxを拡張する簡単な方法です。

拡張機能の setup 関数、またはプロジェクトの conf.py にある setup 関数で Sphinx.connect() を使用して、関数をイベントに接続します。

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(env, node, contnode)
       - event.warn-missing-reference(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 にない文書名を追加することはできません）。

文書名を削除することもできます。 変更されたファイルを未変更として扱うため、注意して行ってください。

バージョン1.3で追加されました。

source-read(app, docname, content)

パラメータ:

• app – Sphinx

• docname – str

• content – インクルードされたファイルの内容を表す、単一の要素を持つ list[str]。

ソースファイルが読み取られたときに発行されます。

content を処理してこの項目を置き換え、ソースレベルの変換を実装できます。

たとえば、LaTeXのように、インライン数式を区切るために $ 記号を使用する場合、正規表現を使用して $...$ を :math:`...` に置き換えることができます。

バージョン0.5で追加されました。

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

パラメータ:

• app – Sphinx

• **relative_path** - Path ソースディレクトリを基準としたインクルードされたファイルを表します。

• **parent_docname** - include ディレクティブを含むドキュメント名の str 。

• content – インクルードされたファイルの内容を表す、単一の要素を持つ list[str]。

include ディレクティブを使用してファイルが読み取られたときに発行されます。

source-read イベントと同様に、 content を処理してこの項目を置き換え、インクルードされたコンテンツを変換できます。

バージョン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が環境によって解析および読み取られ、pickle化されようとしているときに発行されます。 doctree は、その場で変更できます。

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

パラメータ:

• app – Sphinx

• env – BuildEnvironment

• node – 解決されるべき pending_xref ノード。その reftype、reftarget、modname、および classname 属性は、参照のタイプとターゲットを決定します。

• contnode – 将来の参照内のテキストとフォーマットを保持し、返される参照ノードの子であるべきノード。

戻り値:

ドキュメントツリーにノードの代わりに挿入される新しいノード、または他のハンドラに処理を任せる場合は None。

オブジェクトへの相互参照を解決できない場合に発生します。イベントハンドラが参照を解決できる場合は、ノード *node* の代わりにドキュメントツリーに挿入される新しい docutils ノードを返す必要があります。通常、このノードは、子として *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

doctree が環境によって「解決」されたときに発生します。つまり、すべての参照が解決され、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 の反復可能オブジェクト

すべてのドキュメントを読み込んだ後、環境とすべての doctree が最新の状態になったときに発生します。

ハンドラから docnames の反復可能オブジェクトを返すことができます。これらのドキュメントは更新されたと見なされ、書き込みフェーズ中に（再）書き込まれます。

バージョン0.5で追加されました。

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

env-get-updated(app, env)

パラメータ:

• app – Sphinx

• env – BuildEnvironment

戻り値:

str の反復可能オブジェクト

環境が、どのソースファイルが変更され、再読み込みする必要があるかを判断したときに発生します。再読み込みする docnames の反復可能オブジェクトを返すことができます。

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* と *templatename* が文字列、*context* が dict[str, Any] である (pagename, context, templatename) の反復可能オブジェクト。

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 ビルダーがテンプレートをレンダリングするためのコンテキスト辞書を作成したときに発生します。これは、コンテキストにカスタム要素を追加するために使用できます。

*pagename* 引数は、レンダリングされるページの正式名称です。つまり、.html 拡張子なしで、パス区切り文字としてスラッシュを使用します。 *templatename* はレンダリングするテンプレートの名前です。reStructuredText ドキュメントのすべてのページで 'page.html' になります。

*context* 引数は、テンプレートエンジンにページをレンダリングするために渡される値の辞書であり、カスタム値を含めるように変更できます。

*doctree* 引数は、ページが reStructuredText ドキュメントから作成された場合は doctree になります。ページが HTML テンプレート単独から作成された場合は None になります。

ハンドラから文字列を返すことができます。その文字列はこのページの HTML テンプレートとして 'page.html' を置き換えます。

ヒント

Sphinx.add_js_file() および Sphinx.add_css_file() を介して特定のページの JS/CSS ファイルをインストールできます（v3.5.0 以降）。

バージョン 0.4 で追加されました。

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

linkcheck-process-uri(app, uri)

パラメータ:

• app – Sphinx

• uri – 収集された URI の str

戻り値:

str または None

linkcheck ビルダーがドキュメントからハイパーリンクを収集するときに発生します。

イベントハンドラは、文字列を返すことで URI を変更できます。

バージョン 4.1 で追加されました。

前へ

アプリケーション API

次へ

プロジェクト API