拡張

たくさんのプロジェクトではそのドキュメントに独自の機能を必要としているため、Sphinxでは "拡張" をビルド中に加える事が出来ます。拡張により、ドキュメント処理中のほぼすべての場面に変更を加える事が出来ます。

この章ではSphinxに標準で付属している拡張について説明します。ご自身の拡張を実装するときに必要なAPIドキュメントは、 Sphinx拡張機能の開発 を参照してください。

組み込みの拡張

これらの拡張機能はすべてSphinxに組み込まれています。設定ファイルの extensions のリストの中に名前を書くことで使用できるようになります:

サードパーティ製の拡張機能

課題

This should reference the GitHub organization now

多くのコントリビューターによる拡張機能を、 Sphinx Contrib リポジトリで見つけることができます。このリポジトリは、拡張機能をオープンな場でメンテナンスしたい人に公開しています。必要な方は、Georgまで書き込み権限の追加をお願いするメッセージを送ってください。

多くの拡張が各所で公開もされています。Sphinx extension surveyawesome-sphinxdoc には包括的なリストが掲載されています.

もしあなたが作成した拡張が他の人にも有用だと思う、あるいはSphinxの一部として含めるべきだと思うのであれば、 Sphinxのメーリングリストに投稿してください。 ( ここから参加してください )

自分自身の拡張機能はどこに置くべき?

あるプロジェクトに固有の拡張は、そのプロジェクトのディレクトリ構造内に置かれるべきです。Pythonのモジュール検索パス``sys.path``を設定してSphinxがそれらの拡張を見つけられるようにしてください。例えば、ご自身の拡張機能が foo.py``という名前で、プロジェクトのルート配下のサブディレクトリ``exts に置かれていた場合には、 conf.py の中に以下のような記述をします:

import sys, os

sys.path.append(os.path.abspath('exts'))

extensions = ['foo']

sys.pathを使う以外の方法では、site-packagesディレクトリの中にインストールするという方法などもあります。