..

sphinx.ext.intersphinx – 他のプロジェクトのドキュメントへのリンク

バージョン 0.5 で追加.

この拡張機能は他のプロジェクトのPythonオブジェクトのドキュメントに対して、自動リンクを生成することができるようになります。この拡張機能は以下のように動作します。

• Sphinxを使って生成されたHTMLの中には objects.inv というファイルがあります。このファイルの中にはPythonの識別子とHTMLのルートからの相対URLのマッピング情報が含まれます。

• intersphinx拡張を使用したプロジェクトは、 intersphinx_mapping という設定値を使って、そのマッピングファイルの場所を指定することができます。このマッピング情報は、リンクが解決されていないPythonオブジェクトの参照から、外部のドキュメントのリンクを張るために使用されます。

デフォルトの設定では、マッピングファイルはドキュメントと同じ位置にあるとみなされます。マッピングファイルの場所は個別に指定することができます。例えば、インターネットのアクセスができない環境でビルドできるようにする場合などです。

Sphinx間リンクを使用する場合には、 extensions 設定値に 'sphinx.ext.intersphinx' を追加します。追加すると、リンクを有効にするための新しい設定値が追加されます。

intersphinx_mapping

この設定値はURI同士(値は場合によってはNone)をマッピングする辞書になります。キーは外部のSphinxのドキュメントのベースのURIを設定します。ローカルのパス、もしくはHTTPのURIが使用できます。値の法はインベントリーファイル(.inv)がある場所を設定します。これに設定できるのは、None(base UIと同じ場所にあるとみなされます)、もしくはローカルのパス、HTTPのURIのどれかになります。

相対的なローカルパスがキーに設定された場合には、ビルドドキュメントに対して相対的な場所であるとみなされます。値側に相対パスが設定された場合には、ソースディレクトリからの相対パスになります。

例えば、Pythonの標準のライブラリドキュメントの中のモジュールやオブジェクトに対してリンクが張りたい場合には以下のようにします:

intersphinx_mapping = {'http://docs.python.org/dev': None}

これを設定すると、ソースディレクトリの中の python.inv からインベントリー情報を読み込み、 http://docs.python.org/dev 以下のページに対するリンクを作成します。もしもPythonのドキュメントに新しいオブジェクトが追加された場合には、自分でアップデートする必要があります。

リモートでインベントリーファイルを取得する場合には、環境変数の $HTTP_PROXY を設定しておくと、プロキシーを経由してアクセスを行います。

intersphinx_cache_limit

リモートのインベントリーをキャッシュする最長の日数を設定します。デフォルトは5で、5日間という意味になります。マイナスの値を設定すると、インベントリーのキャッシュの日数による制限がなくなります。