Sphinx API¶
多くのプロジェクトではドキュメントに特別な機能が必要となるため、Sphinx はいくつかのレベルで拡張できるように設計されています。
拡張機能でできることの例を次に示します。
解析されたドキュメントの新しい出力形式またはアクションをサポートするために、新しい ビルダー を追加します。
Docutils マークアップ API を使用してマークアップを拡張し、カスタムの reStructuredText ロールとディレクティブを登録します。
ビルドプロセス全体の戦略的な場所に、いわゆる「フックポイント」にカスタムコードを追加することで、フックを登録して特殊なコードを実行できます。たとえば、イベントコールバック API を参照してください。
拡張機能は、単に setup() 関数を持つ Python モジュールです。ユーザーは、拡張機能のモジュール名（またはサブモジュール）を extensions 設定値に配置することで、拡張機能をアクティブにします。
sphinx-build が実行されると、Sphinx はリストされている各モジュールをインポートしようと試み、yourmodule.setup(app) を実行します。この関数は、拡張機能を準備するために使用されます（たとえば、Python コードを実行することにより）。Sphinx がビルドプロセスで使用するリソース（CSS ファイルや HTML ファイルなど）をリンクし、拡張機能が提供するすべてのもの（ディレクティブやロールの定義など）を Sphinx に通知します。app 引数は Sphinx のインスタンスであり、Sphinx ビルドのほとんどの側面を制御できます。
注意
設定ファイル自体に setup() 関数が含まれている場合、設定ファイルは拡張機能として扱うことができます。ロードする他のすべての拡張機能は、extensions 設定値にリストする必要があります。
このページの残りの部分では、拡張機能の開発と Sphinx の動作を制御できるさまざまな部分のいくつかの高度な側面について説明します。拡張機能を構築して Sphinx のさまざまな部分を制御する方法の例については、チュートリアル を参照してください。
重要なオブジェクト¶
拡張機能の作成中に使用する API を持つ重要なオブジェクトがいくつかあります。それらは次のとおりです。
- アプリケーション
アプリケーションオブジェクト（通常は
appと呼ばれます）は、Sphinxのインスタンスです。拡張機能のセットアップ、イベントディスパッチ、出力の生成（ロギング）など、ほとんどの高レベル機能を制御します。環境オブジェクトがある場合、アプリケーションは
env.appとして使用できます。- 環境
ビルド環境オブジェクト（通常は
envと呼ばれます）は、BuildEnvironmentのインスタンスです。ソースドキュメントの解析、ドキュメントコレクションに関するすべてのメタデータの保存、および各ビルド後のディスクへのシリアル化を担当します。その API は、メタデータへのアクセス、参照の解決などに関連するメソッドを提供します。また、拡張機能によって、増分再構築のために永続化する必要がある情報をキャッシュするためにも使用できます。
アプリケーションオブジェクトまたはビルダーオブジェクトがある場合、環境は
app.envまたはbuilder.envとして使用できます。- ビルダー
ビルダーオブジェクト（通常は
builderと呼ばれます）は、Builderの特定のサブクラスのインスタンスです。各ビルダークラスは、解析されたドキュメントを出力形式に変換する方法、またはそれらを処理する方法（たとえば、外部リンクを確認する）を知っています。アプリケーションオブジェクトがある場合、ビルダーは
app.builderとして使用できます。- 設定
設定オブジェクト（通常は
configと呼ばれます）は、conf.pyで設定された設定値の値を属性として提供します。Configのインスタンスです。設定は、
app.configまたはenv.configとして使用できます。
これらのオブジェクトの使用例については、チュートリアル を参照してください。
ビルドフェーズ¶
拡張メカニズムを理解するために不可欠なことの1つは、Sphinx プロジェクトのビルド方法です。これはいくつかのフェーズで機能します。
フェーズ 0：初期化
このフェーズでは、私たちにとって興味深いことはほとんど起こりません。ソースディレクトリでソースファイルが検索され、拡張機能が初期化されます。保存されたビルド環境が存在する場合はロードされ、そうでない場合は新しい環境が作成されます。
フェーズ 1：読み取り
フェーズ 1 では、すべてのソースファイル（および後続のビルドでは、新規または変更されたファイル）が読み取られ、解析されます。これは、ディレクティブとロールが docutils によって検出され、対応するコードが実行されるフェーズです。このフェーズの出力は、各ソースファイルの *doctree* です。つまり、docutils ノードのツリーです。すべての既存のファイルが読み取られるまで完全にはわからないドキュメント要素の場合、一時ノードが作成されます。
docutils によって提供されるノードがあり、docutils のドキュメント に記載されています。追加のノードは Sphinx によって提供され、ここに記載されています。
読み取り中、ビルド環境は、ラベル、見出しの名前、記述された Python オブジェクト、索引エントリなど、読み取りドキュメントのすべてのメタデータと相互参照データで更新されます。これは後で一時ノードを置き換えるために使用されます。
解析された doctree はディスクに保存されます。これは、すべてをメモリに保持することができないためです。
フェーズ 2：整合性チェック
ビルドされたドキュメントに予期しないことがないように、いくつかのチェックが行われます。
フェーズ 3：解決
すべての既存のドキュメントのメタデータと相互参照データがわかったので、すべての一時ノードは、変換と呼ばれるコンポーネントを使用して出力に変換できるノードに置き換えられます。たとえば、存在するオブジェクト参照のリンクが作成され、存在しないオブジェクト参照には単純なリテラルノードが作成されます。
フェーズ 4：書き込み
このフェーズでは、解決された doctree を、HTML や LaTeX などの目的の出力形式に変換します。これは、各 doctree の個々のノードにアクセスし、その過程で何らかの出力を生成する、いわゆる docutils ライターを介して行われます。
注意
一部のビルダーはこの一般的なビルドプランから逸脱しています。たとえば、外部リンクをチェックするビルダーは、解析された doctree 以上は必要としないため、フェーズ 2〜4 はありません。
アプリケーションの例については、ビルドプロセスの拡張 を参照してください。
拡張メタデータ¶
バージョン 1.3 で追加されました。
setup() 関数は辞書を返すことができます。これは Sphinx によって拡張機能のメタデータとして扱われます。現在認識されているメタデータキーは次のとおりです。
'version'：拡張機能のバージョンを識別する文字列。拡張機能のバージョン要件チェック（needs_extensionsを参照）および情報提供の目的で使用されます。指定されていない場合は、"不明なバージョン"に置き換えられます。'env_version'：拡張機能が環境にデータを保存する場合、env データ構造のバージョンを識別する整数。データ構造が前回のビルドから変更されたかどうかを検出するために使用されます。データ構造が変更された場合、拡張機能はバージョンを増やす必要があります。指定されていない場合、Sphinx は拡張機能が環境にデータを保存しないと見なします。'parallel_read_safe'：拡張機能がロードされているときに、ソースファイルの並列読み取りを使用できるかどうかを指定するブール値。デフォルトはFalseです。つまり、拡張機能が並列読み取りセーフであることを確認した後、明示的に指定する必要があります。注意
*並列読み取りセーフ* 拡張機能は、次の条件を満たす必要があります。
拡張機能のコアロジックは、読み取りフェーズ中に並列実行可能です。
読み取りフェーズ中にビルド環境オブジェクト（env）にデータを保存する場合、
env-merge-infoイベントとenv-purge-docイベントのイベントハンドラーがあります。
'parallel_write_safe'：拡張機能がロードされているときに、出力ファイルの並列書き込みを使用できるかどうかを指定するブール値。拡張機能は通常、プロセスに悪影響を及ぼさないため、デフォルトはTrueです。注意
*並列書き込みセーフ*拡張機能は、次の条件を満たす必要があります。
拡張機能のコアロジックは、書き込みフェーズ中に並列実行可能です。
拡張機能の作成に使用されるAPI¶
これらのセクションでは、Sphinx拡張機能を開発する際に利用できるツールについて、より詳細な説明を提供します。一部はSphinxのコア（アプリケーションAPIなど）であり、その他は特定の動作をトリガーします（i18n APIなど）。