多くのプロジェクトはドキュメントの作成に関して特別な機能を必要とするでしょう。Sphinxはさまざまなレベルで拡張ができるように設計されています。
拡張機能を通じてできることは主に３つあります。一つ目は新しい出力形式に対応したり、ドキュメントパース時の新しいアクションをサポートするために、ビルダーを追加することができます。二つ目は、reStructuredText用の、新しいカスタムのロールやディレクティブを追加したり、マークアップを拡張したりすることができます。三つ目は”フックポイント”と呼ばれるもので、ビルドプロセスのさまざまな箇所に存在していて、特別なコードを実行するためのフックを登録することができます。
Sphinx拡張はシンプルなPythonモジュールです。拡張機能がロードされる時には、Sphinxはこのモジュールをインポートして、モジュール内にあるsetup()関数を呼び出します。この関数の中では拡張機能が提供するものをするものをSphinxに知らせます。詳しくはSphinx拡張のチュートリアルの例を見てください。
設定ファイルそのものも、setup()関数を持っている場合には拡張機能として扱われます。それ以外のロードが必要なすべての拡張機能は、設定ファイルの中の extensions の中にリストアップしてください。
これらの拡張機能はすべてSphinxに組み込まれています。設定ファイルの extensions のリストの中に名前を書くことで使用することができるようになります:
Sphinxのディストリビューション内で(まだ)メンテナンスされていない拡張機能もいくつか存在します。 BitBucketのWiki の中に、これらのリストがあります。
もしも他の人から見て便利そうに見えると思えるような拡張機能を書いた場合には、プロジェクトのメーリングリスト(sphinx-dev@googlegroups.com)に知らせてください。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ディレクトリの中にインストールするという方法などもあります。k