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

バージョン 0.5 で追加.

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

使用方法はシンプルで、Sphinxがクロスリファレンスの参照を解決しようとして、現在のドキュメントの中から見つけられなかった場合には、 intersphinx_mapping で設定されたドキュメント集の中を探索しにいくようになります。 :py:class:`zipfile.ZipFile` という参照があった場合には、そのドキュメントの詳細な場所を知らなくても、Pythonの標準ライブラリのドキュメントの、ZipFileクラスに対してリンクが張られます。

もし、「新しい」フォーマット(後述)を使用する場合、リンクターゲット名に特定のプリフィックスを付けることで、強制的に外部ドキュメントを探索しにいくように設定できます。 :ref:`比較マニュアル <python:comparisons>` というリンクがあれば、もし"python"という名前のドキュメントセットが設定されていたとすると、その中の"comparisons"というラベルを探索しに行きます。

この仕組みの背後では、次のようなことが行われています。

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

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

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

設定

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

intersphinx_mapping

この設定値には、このドキュメントからリンクさせる他のプロジェクトの場所と名前を設定します。

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

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

この設定値の古いフォーマット

このフォーマットはSphinx 1.0以前で使用されていました。これは現在でも使用できます。

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

この設定値の新しいフォーマット

バージョン 1.0 で追加.

A dictionary mapping unique identifiers to a tuple (target, inventory). Each target is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. The inventory indicates where the inventory file can be found: it can be None (an objects.inv file at the same location as the base URI) or another local file path or a full HTTP URI to an inventory file.

ユニークな識別子は、クロスリファレンスのターゲットのプリフィックスとして使用されます。そのため、ターゲットの要素がintersphinxによって設定されたことが明確になります。たとえば、 :ref:`比較のマニュアル <python:comparisons>` という項目があれば、この"comparisons"というラベルは"python"のドキュメントセットの中にあるドキュメントに対してリンクが作成されます。

サンプル

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

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

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

2番目のサンプルは、2つ目のタプルの要素に None ではない値を与える場合です:

intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                  'python-inv.txt')}

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

Multiple targets for the inventory

バージョン 1.3 で追加.

各インベントリへの代替ファイルを指定できます。次の例に示すように、1つは、二番目のインベントリタプル項目に対してもタプルを与えることができます。これは最初に成功したフェッチまで、 (次の)タプルを反復処理で読みこみます。この記法の基本ユースケースはプライマリインベントリのサーバーダウン時用のミラーサイトを指定することです。

intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                  (None, 'python-inv.txt'))}

For a set of books edited and tested locally and then published together, it could be helpful to try a local inventory file first, to check references before publication:

intersphinx_mapping = {
    'otherbook':
        ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
            ('../../otherbook/build/html/objects.inv', None)),
}
intersphinx_cache_limit

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

intersphinx_timeout

タイムアウトの秒数を設定します。デフォルトは None で、タイムアウトしません。

注釈

タイムアウト時間は、通信時間全体の時間ではなく、サーバーが応答を返し始めるまでの時間です。指定した秒数位内に応答を開始しない場合、例外が発生します。

基本認可のinventoryファイルでのIntersphinxの使用

Intersphinx は、次のような基本認可をサポートしています。

intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
                                  None)}

ユーザーとパスワードは、リンクの生成時にURLから削除されます。