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

バージョン 0.5 で追加.

This extension can generate links to the documentation of objects in external projects, either explicitly through the external role, or as a fallback resolution for any other cross-reference.

Usage for fallback resolution is simple: whenever Sphinx encounters a cross-reference that has no matching target in the current documentation set, it looks for targets in the external documentation sets configured in intersphinx_mapping. A reference like :py:class:`zipfile.ZipFile` can then link to the Python documentation for the ZipFile class, without you having to specify where it is located exactly.

When using the external role, you can force lookup to any external projects, and optionally to a specific external project. A link like :external:ref:`comparison manual <comparisons>` will then link to the label "comparisons" in whichever configured external project, if it exists, and a link like :external+python:ref:`comparison manual <comparisons>` will link to the label "comparisons" only in the doc set "python", if it exists.

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

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

  • Projects using the Intersphinx extension can specify the location of such mapping files in the intersphinx_mapping config value. The mapping will then be used to resolve both external references, and also otherwise missing references to objects into links to the other documentation.

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

設定

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

intersphinx_mapping

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

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

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

Format

バージョン 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.

The unique identifier can be used in the external role, so that it is clear which intersphinx set the target belongs to. A link like external:python+ref:`comparison manual <comparisons>` will link to the label "comparisons" in the doc set "python", if it exists.

サンプル

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)),
}

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

バージョン 6.2 で非推奨.

注意

This is the format used before Sphinx 1.0. It is deprecated and will be removed in Sphinx 8.0.

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

例:

intersphinx_mapping = {'https://docs.python.org/': None}
intersphinx_cache_limit

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

intersphinx_timeout

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

注釈

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

intersphinx_disabled_reftypes

バージョン 4.3 で追加.

バージョン 5.0 で変更: Changed default value from an empty list to ['std:doc'].

A list of strings being either:

  • the name of a specific reference type in a domain, e.g., std:doc, py:func, or cpp:class,

  • the name of a domain, and a wildcard, e.g., std:*, py:*, or cpp:*, or

  • simply a wildcard *.

The default value is ['std:doc'].

When a non-external cross-reference is being resolved by intersphinx, skip resolution if it matches one of the specifications in this list.

For example, with intersphinx_disabled_reftypes = ['std:doc'] a cross-reference :doc:`installation` will not be attempted to be resolved by intersphinx, but :external+otherbook:doc:`installation` will be attempted to be resolved in the inventory named otherbook in intersphinx_mapping. At the same time, all cross-references generated in, e.g., Python, declarations will still be attempted to be resolved by intersphinx.

If * is in the list of domains, then no non-external references will be resolved by intersphinx.

Explicitly Reference External Objects

The Intersphinx extension provides the following role.

:external:

バージョン 4.4 で追加.

Use Intersphinx to perform lookup only in external projects, and not the current project. Intersphinx still needs to know the type of object you would like to find, so the general form of this role is to write the cross-refererence as if the object is in the current project, but then prefix it with :external. The two forms are then

  • :external:domain:reftype:`target`, e.g., :external:py:class:`zipfile.ZipFile`, or

  • :external:reftype:`target`, e.g., :external:doc:`installation`.

If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in intersphinx_mapping, is added as well to get the two forms

  • :external+invname:domain:reftype:`target`, e.g., :external+python:py:class:`zipfile.ZipFile`, or

  • :external+invname:reftype:`target`, e.g., :external+python:doc:`installation`.

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

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

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

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