Sphinx拡張機能の開発

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

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

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

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

Discovery of builders by entry point

バージョン 1.6 で追加.

Builder extensions can be discovered by means of entry points so that they do not have to be listed in the extensions configuration value.

Builder extensions should define an entry point in the sphinx.builders group. The name of the entry point needs to match your builder's name attribute, which is the name passed to the sphinx-build -b option. The entry point value should equal the dotted name of the extension module. Here is an example of how an entry point for 'mybuilder' can be defined in the extension's setup.py:

setup(
    # ...
    entry_points={
        'sphinx.builders': [
            'mybuilder = my.extension.module',
        ],
    }
)

Note that it is still necessary to register the builder using add_builder() in the extension's setup() function.

重要なオブジェクト

There are several key objects whose API you will use while writing an extension. These are:

アプリケーション

アプリケーションオブジェクト(通常 app と呼ばれる)は Sphinx のインスタンスです。これは高位の機能をコントロールします。例えば、拡張のセットアップや、イベントのディスパッチ、アウトプットの生成(ロギング)等です。

もし、環境オブジェクトがあれば、 env.app のようにアプリケーションが提供されます。

Environment

ビルド環境オブジェクト(通常 env と呼ばれる)は BuildEnvironment のインスタンスです。これはドキュメントソースのパースを行い、ドキュメントセットに関する全てのメタデータを保持し、それらをビルド後にディスクにシリアライズする責任を持っています。

環境オブジェクトはメタデータにアクセスするためのAPIや、参照を解決するAPIなどを持っています。それはまた、拡張から情報のキャッシュとして使われ、それによって漸進的な再ビルドができます。

もしアプリケーションかビルダーのオブジェクトがあれば、 app.envbuilder.env のように環境オブジェクトが提供されます。

ビルダー

ビルダーオブジェクト(通常 builder と呼ばれる)は Builder のサブクラスのインスタンスです。各ビルダークラスはパースしたドキュメントを使って、出力フォーマットに変換したり、データ処理したりします(例えば、外部リンクのチェックなど)。

もしアプリケーションオブジェクトがあれば、 app.builder のようにビルダーオブジェクトが提供されます。

Config

コンフィグオブジェクト(通常 config と呼ばれる)は conf.py の設定値を属性として提供します。これは Config のインスタンスです。

コンフィグオブジェクトは app.configenv.config として提供されます。

To see an example of use of these objects, refer to 拡張機能のチュートリアル.

ビルド・フェーズ

Sphinxのプロジェクトがビルドされる過程で、拡張機能がどのように実行されるのかということを理解することは、拡張機能の開発をするうえで必要不可欠です。この作業は以下のいくつかのフェーズから構成されています。

フェーズ 0: 初期化

このフェーズでは拡張作成者にとって面白いものは何もありません。 ソースディレクトリ内のソースファイルを探索し、拡張機能を初期化します。 保存されたビルド環境があればそれをロードし、なければ新しいビルド環境を作成します。

フェーズ 1: 読み込み

フェーズ 1ではすべてのソースファイルが読み込まれ、パースされます。なお、この後のフェーズは新規のファイルか変更されたファイルに対して実行されます。このフェーズではdocutilsによってディレクティブやロールが処理され、それに対応するコードが実行されます。このフェーズの出力は、ソースファイルごとのdoctreeです。これは、docutilsのノードがツリー上に構成されているものです。すべてのファイルを読み込むまでは完全に解釈できないドキュメントの要素に関しては、一時的なノードが作られます。

docutilsによって提供されるノードがあります。これらは docutilsのドキュメント. で説明されています。追加のノードはSphinxによって提供され、 ドキュメントはここ にあります。

ソースを読み込んでいる間は、ラベルや見出し名、説明されているPythonオブジェクト、索引のエントリーなどのメタな情報やクロスファンレスの情報がビルド環境に出力されます。これらの情報は、後で一時的なノードと置き換えられます。

パースされたDOCツリーはすべてのメモリ上で保存しておくことができないため、ディスク上に保存されます。

フェーズ 2: 一貫性チェック

ビルドされたドキュメントの中に、びっくりするようなものがないか、いくつかのチェックを行います。

フェーズ 3: 解決

Now that the metadata and cross-reference data of all existing documents is known, all temporary nodes are replaced by nodes that can be converted into output using components called transforms. For example, links are created for object references that exist, and simple literal nodes are created for those that don't.

フェーズ 4: 書き出し

このフェーズでは参照が解決されたDOCツリーを、HTMLやLaTeXなどの指定された出力フォーマットに変換します。このプロセス中では、docutilsのライターと呼ばれるものがDOCツリーの個々のノードをたどって、出力を行っていきます。

注釈

いくつかのビルダーの中には、この一般的なビルド計画から外れているものもあります。 例えば、外部リンクチェックのビルダーはdoctreeのパースをする以上の情報は不要なので、フェーズ2~4を行いません。

To see an example of application, refer to "TODO" 拡張機能の開発.

拡張機能のメタデータ

バージョン 1.3 で追加.

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

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

  • 'env_version': an integer that identifies the version of env data structure if the extension stores any data to environment. It is used to detect the data structure has been changed from last build. The extensions have to increment the version when data structure has changed. If not given, Sphinx considers the extension does not stores any data to environment.

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

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