Sphinx拡張機能の開発

多くのプロジェクトはドキュメントの作成に関して特別な機能を必要とするでしょう。Sphinxはさまざまなレベルで拡張ができるように設計されています。

拡張機能を通じてできることは主に3つあります。一つ目は新しい出力形式に対応したり、ドキュメントパース時の新しいアクションをサポートするために、ビルダーを追加できます。二つ目は、reStructuredText用の、新しいカスタムのロールやディレクティブを追加したり、マークアップを拡張したりできます。三つ目は”フックポイント”と呼ばれるもので、ビルドプロセスのさまざまな箇所に存在していて、特別なコードを実行するためのフックを登録できます。

Sphinx拡張はシンプルなPythonモジュールです。拡張機能がロードされる時には、Sphinxはこのモジュールをインポートして、モジュール内にあるsetup()関数を呼び出します。この関数の中では拡張機能が提供するものをSphinxに知らせます。詳しくはSphinx拡張のチュートリアルの例を見てください。

設定ファイルそのものも、setup()関数を持っている場合には拡張機能として扱われます。それ以外のロードが必要なすべての拡張機能は、設定ファイルの中の extensions の中にリストアップしてください。

拡張機能のメタデータ

バージョン 1.3 で追加.

setup()関数は、ディクショナリを返すよう定義します。Sphinxはそのディクショナリを拡張機能のメタデータとして解釈します。 メタデータのキーとして解釈可能なものは以下のとおりです。

  • 'version': 拡張機能のバージョンを示す文字列。 拡張機能の必要バージョンのチェック(needs_extensionsを参考)に利用されたり、参照目的で使われたりします。指定がない場合には、"unknown version"が代わりに指定されます。

  • 'parallel_read_safe': 拡張をロードする際に、ソースファイルの並列読み込みをサポートするかどうかを示す真偽値。デフォルトは False で、拡張機能が parallel-read-safe であるであることを確認してから明示的に指定をすべきです。

  • 'parallel_write_safe': 拡張をロードする際に、出力ファイルの並列書き込みをサポートするかどうかを示す真偽値。デフォルトは False で、拡張機能が parallel-write-safe であるであることを確認してから明示的に指定をすべきです。