拡張

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

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

組み込みの拡張

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

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

You can find several extensions contributed by users in the sphinx-contrib organization. If you wish to include your extension in this organization, simply follow the instructions provided in the github-administration project. This is optional and there are several extensions hosted elsewhere. The awesome-sphinxdoc and sphinx-extensions projects are both curated lists of Sphinx packages, and many packages use the Framework :: Sphinx :: Extension and Framework :: Sphinx :: Theme trove classifiers for Sphinx extensions and themes, respectively.

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

あるプロジェクトに固有の拡張は、そのプロジェクトのディレクトリ構造内に置かれるべきです。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ディレクトリの中にインストールするという方法などもあります。