New in version 0.5.
この拡張機能は他のプロジェクトのオブジェクトのドキュメントに対して、自動リンクを生成することができるようになります。
使用方法はシンプルで、Sphinxがクロスリファレンスの参照を解決しようとして、現在のドキュメントの中から見つけられなかった場合には、 intersphinx_mapping で設定されたドキュメント集の中を探索しにいくようになります。 :py:class:`zipfile.ZipFile` という参照があった場合には、そのドキュメントの詳細な場所を知らなくても、Pythonの標準ライブラリのドキュメントの、ZipFileクラスに対してリンクが張られます。
もし、「新しい」フォーマット(後述)を使用する場合、リンクターゲット名に特定のプリフィックスを付けることで、強制的に外部ドキュメントを探索しにいくように設定することができます。 :ref:`比較マニュアル <python:comparisons>` というリンクがあれば、もし”python”という名前のドキュメントセットが設定されていたとすると、その中の”comparisons”というラベルを探索しに行きます。
この仕組みの背後では、次のようなことが行われています。
デフォルトの設定では、マッピングファイルはドキュメントと同じ位置にあるとみなされます。マッピングファイルの場所は個別に指定することができます。例えば、インターネットのアクセスができない環境でビルドできるようにする場合などです。
Sphinx間リンクを使用する場合には、 extensions 設定値に 'sphinx.ext.intersphinx' を追加します。追加すると、リンクを有効にするための新しい設定値が追加されます。
この設定値には、このドキュメントからリンクさせる他のプロジェクトの場所と名前を設定します。
相対的なローカルパスがキーに設定された場合には、ビルドドキュメントに対して相対的な場所であるとみなされます。値側に相対パスが設定された場合には、ソースディレクトリからの相対パスになります。
リモートでインベントリーファイルを取得する場合には、環境変数の $HTTP_PROXY を設定しておくと、プロキシーを経由してアクセスを行います。
この設定値の古いフォーマット
このフォーマットはSphinx 1.0以前で使用されていました。これは現在でも使用できます。
この設定値はURI同士(値は場合によってはNone)をマッピングする辞書になります。キーは外部のSphinxのドキュメントのベースのURIを設定します。ローカルのパス、もしくはHTTPのURIが使用できます。値はインベントリファイル(.inv)がある場所を設定します。これに設定できるのは、None(base UIと同じ場所にあるとみなされます)、もしくはローカルのパス、HTTPのURIのどれかになります。
この設定値の新しいフォーマット
New in version 1.0.
ユニークな識別子をキーにして、 (ターゲット, インベントリ) というタプルを値に持つ辞書のマッピングです。それぞれの ターゲット は外部のSphinxのドキュメントを表すベースのURIで、ローカルファイルパスもしくはHTTPのURIを指定できます。 インベントリ はインベントリファイル(.inv)がある場所を設定します。これに設定できるのは、None(ベースURIと同じ場所にあるとみなされます)、もしくはローカルのパス、HTTPのURIのどれかになります。
ユニークな識別子は、クロスリファレンスのターゲットのプリフィックスとして使用されます。そのため、ターゲットの要素がintersphinxによって設定されたことが明確になります。たとえば、 :ref:`比較のマニュアル <python:comparisons>` という項目があれば、この”comparisons”というラベルは”python”のドキュメントセットの中にあるドキュメントに対してリンクが作成されます。
サンプル
Pythonの標準のライブラリドキュメントの中のモジュールやオブジェクトに対してリンクが張りたい場合には次のようにします:
intersphinx_mapping = {'python': ('http://docs.python.org/', None)}
これを設定すると、ソースディレクトリの中の python.inv からインベントリー情報を読み込み、 http://docs.python.org/ 以下のページに対するリンクを作成します。ダウンロードされたインベントリ情報はキャッシュされるので、もしもPythonのドキュメントに新しいオブジェクトが追加された場合には、自分でアップデートする必要があります。
2番目のサンプルは、2つ目のタプルの要素に None ではない値を与える場合です:
intersphinx_mapping = {'python': ('http://docs.python.org/':
'python-inv.txt')}
これを設定すると、ソースディレクトリの中の python-inv.txt からインベントリー情報を読み込みますが、先ほどの例と同じように http://docs.python.org/ 以下のページに対するリンクを作成します。もしもPythonのドキュメントに新しいオブジェクトが追加された場合には、自分でアップデートする必要があります。
リモートのインベントリーをキャッシュする最長の日数を設定します。デフォルトは5で、5日間という意味になります。マイナスの値を設定すると、インベントリーのキャッシュの日数による制限がなくなります。