sphinx.ext.intersphinx – 他のプロジェクトのドキュメントへのリンク¶
バージョン 0.5 で追加されました。
この拡張機能は、外部プロジェクトのオブジェクトのドキュメントへのリンクを生成できます。 external ロールを明示的に使用するか、他のクロスリファレンスのフォールバック解決策として使用できます。
フォールバック解決策としての使用方法は簡単です。Sphinxが現在のドキュメントセットに一致するターゲットを持たないクロスリファレンスに遭遇するたびに、 intersphinx_mapping で設定された外部ドキュメントセットでターゲットを探します。 :py:class:`zipfile.ZipFile` のような参照は、ZipFileクラスのPythonドキュメントへのリンクを生成できます。その場所を正確に指定する必要はありません。
external ロールを使用する場合、任意の外部プロジェクト、またはオプションで特定の外部プロジェクトへのルックアップを強制できます。 :external:ref:`comparison manual <comparisons>` のようなリンクは、設定された外部プロジェクトのいずれかにラベル "comparisons" が存在する場合、それにリンクします。 :external+python:ref:`comparison manual <comparisons>` のようなリンクは、ドキュメントセット "python" にラベル "comparisons" が存在する場合、それにのみリンクします。
背後では、これは次のように動作します
各Sphinx HTMLビルドは、オブジェクト名からHTMLセットのルートに対する相対URIへのマッピングを含む
objects.invという名前のファイルを作成します。Intersphinx拡張機能を使用するプロジェクトは、
intersphinx_mapping設定値でそのようなマッピングファイルの場所を指定できます。マッピングは、external参照と、オブジェクトへのその他の見つからない参照の両方を他のドキュメントへのリンクに解決するために使用されます。デフォルトでは、マッピングファイルはドキュメントの残りの部分と同じ場所にあると想定されています。ただし、マッピングファイルの場所は個別に指定することもできます。たとえば、ドキュメントをインターネットアクセスなしでビルドできるようにする場合などです。
設定¶
Intersphinxリンクを使用するには、 'sphinx.ext.intersphinx' を extensions 設定値に追加し、これらの設定値を使用してリンクをアクティブにします
- intersphinx_mapping¶
この設定値には、このドキュメントにリンクする必要がある他のプロジェクトの場所と名前が含まれています。
ターゲット場所の相対ローカルパスは、ビルドされたドキュメントのベースからの相対パスとして扱われます。一方、インベントリ場所の相対ローカルパスは、ソースディレクトリからの相対パスとして扱われます。
リモートインベントリファイルをフェッチする場合、プロキシ設定は
$HTTP_PROXY環境変数から読み取られます。フォーマット
バージョン 1.0 で追加されました。
一意の識別子をタプル
(target, inventory)にマッピングする辞書。 各targetは、外部SphinxドキュメントセットのベースURIであり、ローカルパスまたはHTTP URIにすることができます。inventoryは、インベントリファイルが見つかる場所を示します。None（ベースURIと同じ場所にあるobjects.invファイル）、別のローカルファイルパス、またはインベントリファイルへの完全なHTTP URIにすることができます。一意の識別子は、
externalロールで使用して、ターゲットがどのintersphinxセットに属しているかを明確にすることができます。external:python+ref:`comparison manual <comparisons>`のようなリンクは、ドキュメントセット "python" にラベル "comparisons" が存在する場合、それにリンクします。例
Python標準ライブラリドキュメントのモジュールとオブジェクトへのリンクを追加するには、次を使用します
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
これは、インターネットから対応する
objects.invファイルをダウンロードし、指定されたURIの下のページへのリンクを生成します。 ダウンロードされたインベントリはSphinx環境にキャッシュされるため、完全な再構築を行うたびに再ダウンロードする必要があります。2番目の例は、2番目のタプル項目の
None以外の値の意味を示していますintersphinx_mapping = {'python': ('https://docs.python.org/3', 'python-inv.txt')}
これは、ソースディレクトリの
python-inv.txtからインベントリを読み取りますが、https://docs.python.org/3の下のページへのリンクを生成します。 Pythonドキュメントに新しいオブジェクトが追加されたときにインベントリファイルを更新するのはあなた次第です。インベントリの複数ターゲット
バージョン 1.3 で追加されました。
各インベントリに代替ファイルを指定できます。 次の例に示すように、2番目のインベントリタプル項目にタプルを指定できます。 これは、最初の成功したフェッチまで、（2番目の）タプル項目を反復処理してインベントリを読み取ります。 この主なユースケースは、プライマリアプリケーションのサーバーダウンタイムのミラーサイトを指定することです
intersphinx_mapping = {'python': ('https://docs.python.org/3', (None, 'python-inv.txt'))}
ローカルで編集およびテストされ、一緒に公開される一連の書籍の場合、公開前に参照を確認するために、最初にローカルインベントリファイルを試しることが役立つ場合があります
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で、タイムアウトしないことを意味します。注意
timeout は、レスポンスのダウンロード全体の時間制限ではありません。 むしろ、サーバーが timeout 秒間レスポンスを発行していない場合に例外が発生します。
- intersphinx_disabled_reftypes¶
バージョン 4.3 で追加されました。
バージョン 5.0 で変更: デフォルト値が空リストから
['std:doc']に変更されました。次のいずれかである文字列のリスト
ドメイン内の特定の参照タイプの名前。例：
std:doc、py:func、またはcpp:classドメインの名前とワイルドカード。例：
std:*、py:*、またはcpp:*単なるワイルドカード
*
デフォルト値は
['std:doc']です。external以外のクロスリファレンスがintersphinxによって解決されている場合、このリストのいずれかの仕様に一致する場合は解決をスキップします。例えば、
intersphinx_disabled_reftypes = ['std:doc']と設定すると、クロスリファレンス:doc:`installation`は intersphinx によって解決されようと試みられませんが、:external+otherbook:doc:`installation`はintersphinx_mapping内でotherbookという名前のインベントリ内で解決が試みられます。同時に、例えば Python の宣言などで生成されたすべてのクロスリファレンスは、引き続き intersphinx によって解決が試みられます。ドメインのリストに
*が含まれている場合、external以外の参照は intersphinx によって解決されません。
外部オブジェクトを明示的に参照する¶
Intersphinx 拡張機能は、以下のロールを提供します。
- :external:¶
バージョン 4.4 で追加されました。
Intersphinx を使用して、現在のプロジェクトではなく、外部プロジェクトのみでルックアップを実行します。 Intersphinx は、依然として検索したいオブジェクトのタイプを知る必要があるため、このロールの一般的な形式は、オブジェクトが現在のプロジェクトにあるかのようにクロスリファレンスを記述し、その前に
:externalを付けることです。2 つの形式は次のとおりです。:external:domain:reftype:`target`、例：:external:py:class:`zipfile.ZipFile`、または:external:reftype:`target`、例：:external:doc:`installation`。この省略形では、ドメインはstdと見なされます。
特定の外部プロジェクトにルックアップを制限したい場合は、
intersphinx_mappingで指定されているプロジェクトのキーも追加して、次の 2 つの形式にします。:external+invname:domain:reftype:`target`、例：:external+python:py:class:`zipfile.ZipFile`、または:external+invname:reftype:`target`、例：:external+python:doc:`installation`。
Intersphinx マッピングファイルのすべてのリンクを表示する¶
Intersphinx マッピングファイルのすべての Intersphinx リンクとそのターゲットを表示するには、python -msphinx.ext.intersphinx url-or-path を実行します。これは、ドキュメントプロジェクトで壊れた Intersphinx リンクの根本原因を検索する場合に役立ちます。次の例は、Python 3 ドキュメントの Intersphinx マッピングを出力します。
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv