他のプロジェクトへのリンク¶
sphinx.ext.intersphinx を使うと、このプロジェクトで解決できない参照を他のプロジェクトのインベントリで探します。これは各 Sphinx・Guidedog サイトが公開する objects.inv です。conf.toml にプロジェクトを指定します。
extensions = ["sphinx.ext.intersphinx"]
[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]
各項目には相手のページのアドレスとインベントリの場所を書きます。URL、ソースからの相対ファイル、またはそのアドレスの objects.inv を表す "" を使えます。リストは順に試します。Sphinx の intersphinx_mapping と同じですが、Python の None の代わりに "" を使います。guidedog migrate が変換します。
参照に新しい書き方は不要です。
:func:`len`, :class:`list`, and :ref:`tut-packages` link into Python's documentation.
:ref:`click:testing` looks only in Click's inventory.
:external+python:ref:`tut-packages` never looks in this project.
ラベルと文書へのリンクには相手のタイトルと「(in Python v3.14)」などのツールチップを付けます。Sphinx と同じく、:doc: 参照にはプロジェクト名（:doc:`python:tutorial/index`）が必要です。intersphinx_disabled_reftypes の既定値が ["std:doc"] のためです。
ビルド開始時にインベントリを取得し、_build/.doctrees/__intersphinx_cache__ に intersphinx_cache_limit 日保存します。既定は 5 日、負値なら保持します。ローカルファイルは毎回読みます。Sphinx と同じく URL の転送先ディレクトリをリンクの基準にし、キャッシュにも記録するため、キャッシュ利用時も同じリンクになります。例えば https://werkzeug.palletsprojects.com/objects.inv は /en/stable/ に転送されます。intersphinx_timeout は取得ごとの秒数制限です。到達できないプロジェクトは警告し、参照は未解決のままです。
Guidedog は各ページ、ラベル、用語、オブジェクトを含む objects.inv を書き、他のプロジェクトから同じ方法でリンクできます。