sphinx.ext.intersphinx --他のプロジェクト文書へのリンク

バージョン 0.5 で追加.

この拡張は，他の項目における対象文書へのリンクを自動生成することができる.

使い方は簡単です：Sphinxが現在の文書集合に適合先のない交差引用に遭遇するたびに，中に配置された文書集合でターゲットを検索する. intersphinx_mapping それがそうです。このような引用は :py:class:`zipfile.ZipFile そして，`zipfileクラスのPython文書にリンクすることができ，その正確な位置を指定する必要はない.

“新しい”フォーマットが使用される場合(以下参照)、リンク先の前に適切なプレフィックスを加えることによって、外来セットでの検索を強制することもできます。このようなリンクは :ref:`comparison manual <python:comparisons> そして，`文書セットpython(存在する場合)の“比較”タグにリンクする.

舞台裏では次のような働き方をしています

  • 各Sphinx HTML構築は、1つの名前を作成します。 objects.inv これは，オブジェクト名からHTMLセットのルートに対するURIへのマッピングを含む.

  • Intersphinx拡張プロジェクトを使用して、このようなマッピングファイルを指定することができます intersphinx_mapping 値を配置する。そして，このマッピングは，本来欠落していたオブジェクト参照を他の文書へのリンクとして解析するために用いられる.

  • デフォルトでは、マッピングファイルは文書の残りの部分と同じ位置にあると仮定しているが、例えば、文書がInternetアクセスなしに構築できるはずである場合には、マッピングファイルの位置を個別に指定してもよい。

配置

Intersphinxリンクをご利用の場合は、追加してください 'sphinx.ext.intersphinx' あなたには extensions 構成値を設定し、これらの構成値を使用してリンクをアクティブ化します：

intersphinx_mapping

この配置値は，本稿のプロファイルでリンクすべき他の項目の位置と名前を含む.

ターゲット位置の相対ローカルパスは、構築された文書に対するベースとみなされ、在庫位置の相対ローカルパスは、ソースディレクトリに対するものとみなされる。

リモート·インベントリ·ファイルを取得すると $HTTP_PROXY 環境変数

この構成値の古いフォーマット

これはSphinx 1.0までに使用されているフォーマットである.それはまだ認められている。

URIを以下のいずれかの辞書にマッピングする None またはURI。これらの鍵は、外来Sphinx文書セットの基本URIであり、ローカルパスまたはHTTP URIであってもよい。これらの値はリストファイルの位置を見つけることができることを示しています None (基本URIと同じ位置にある)または別のローカルまたはHTTP URI。

この構成値の新しいフォーマット

バージョン 1.0 で追加.

タプルの辞書に一意の識別子をマッピングします (target, inventory) それがそうです。どれも target 外来Sphinx文書セットの基本URIであり、ローカルパスまたはHTTP URIであってもよい。♪the inventory リストファイルの位置を見つけることができる指示： None (一種) objects.inv 基本URIと同じ位置にあるファイル)または他のローカルファイルパスまたはインベントリファイルの完全なHTTP URI。

一意の識別子は、オブジェクトがどのインターリーブされたターゲットのセットに属するかを明確に知るために、交差参照オブジェクトのプレフィックスとして使用することができる。このようなリンクは :ref:`comparison manual <python:comparisons> `文書セットpythonの比較ラベルにリンクされます(存在する場合)。

Example

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の在庫タプルアイテムのタプルを与えることができる。これは、最初の取得に成功するまで、タプルアイテムによって反復された在庫を読み取るであろう。プライマリ·リストのサーバ停止時間を指定するためのミラーサイトの主な使用状況は以下のとおりである。

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 五日間という意味です。これを負の値に設定して在庫を無制限にキャッシュすることができる.

intersphinx_timeout

タイムアウトの秒数。黙認する. None タイムアウトしないことを示す.

注釈

タイムアウトは全応答ダウンロードの時間制限ではなく，逆にサーバがタイムアウト秒数の応答を出さないと異常を引き起こす.

Intersphinxは、基本的な許可の下でリストファイルと一緒に使用されます。

Intersphinxは、以下の基本的な許可をサポートします。

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

リンクを生成する際には，ユーザとパスワードがURLから剥離される.