クロスリファレンス構文¶

クロスリファレンスは、多くのセマンティックインタープリテッドテキストロールによって生成されます。基本的に、:role:`target` と書くだけで、 *role* で示されるタイプの *target* という名前のアイテムへのリンクが作成されます。リンクのテキストは *target* と同じになります。

ただし、クロスリファレンスロールをより汎用的にする追加機能がいくつかあります。

reStructuredText の直接ハイパーリンクのように、明示的なタイトルと参照ターゲットを指定できます。 :role:`title <target>` は *target* を参照しますが、リンクテキストは *title* になります。
コンテンツの前に ! を付けると、参照/ハイパーリンクは作成されません。
コンテンツの前に ~ を付けると、リンクテキストはターゲットの最後のコンポーネントのみになります。たとえば、:py:meth:`~Queue.Queue.get` は Queue.Queue.get を参照しますが、リンクテキストとして get のみを表示します。これはすべてのクロスリファレンスロールで機能するわけではなく、ドメイン固有です。

HTML出力では、リンクの title 属性（たとえば、マウスホバー時にツールチップとして表示される）は、常に完全なターゲット名になります。

あらゆるものへのクロスリファレンス¶

:any:¶

バージョン 1.3 で追加されました。

このコンビニエンスロールは、参照テキストの有効なターゲットを見つけるために最善を尽くします。

まず、doc、ref、または option によって参照される標準のクロスリファレンスターゲットを試します。

拡張機能によって標準ドメインに追加されたカスタムオブジェクト（Sphinx.add_object_type() を参照）も検索されます。
次に、ロードされたすべてのドメインでオブジェクト（ターゲット）を探します。一致がどれほど具体的でなければならないかは、ドメイン次第です。たとえば、Python ドメインでは、:any:`Builder` の参照は sphinx.builders.Builder クラスと一致します。

ターゲットが見つからないか、複数のターゲットが見つかった場合は、警告が出力されます。複数のターゲットがある場合は、「any」を特定のロールに変更できます。

このロールは、default_role を設定するのに適しています。設定すると、多くのマークアップオーバーヘッドなしにクロスリファレンスを記述できます。たとえば、この Python 関数のドキュメントでは、

.. function:: install()

   This function installs a `handler` for every signal known by the
   `signal` module.  See the section `about-signals` for more information.

用語集の用語（通常は :term:`handler`）、Python モジュール（通常は :py:mod:`signal` または :mod:`signal`）、セクション（通常は :ref:`about-signals`) への参照が考えられます。

any ロールは、intersphinx 拡張機能とも連携します。ローカルクロスリファレンスが見つからない場合、intersphinx インベントリのすべてのオブジェクトタイプも検索されます。

オブジェクトへのクロスリファレンス¶

これらのロールは、それぞれのドメインで説明されています。

任意の場所へのクロスリファレンス¶

:ref:¶

任意のドキュメント内の任意の場所へのクロスリファレンスをサポートするために、標準の reStructuredText ラベルが使用されます。これを実現するには、ラベル名はドキュメント全体で一意である必要があります。ラベルを参照するには、2 つの方法があります。

セクションタイトルの直前にラベルを配置すると、:ref:`label-name` で参照できます。例えば、
```
.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.
```
:ref: ロールは、セクションへのリンクを生成し、リンクタイトルは「クロスリファレンスするセクション」になります。これは、セクションと参照が異なるソースファイルにある場合でも同様に機能します。

自動ラベルは図でも機能します。例えば、
```
.. _my-figure:

.. figure:: whatever

   Figure caption
```
この場合、参照 :ref:`my-figure` は、リンクテキスト「図のキャプション」を使用して図への参照を挿入します。

table ディレクティブを使用して明示的なキャプションが付けられたテーブルでも同じことが機能します。
セクションタイトルの前に配置されていないラベルも参照できますが、:ref:`Link title <label-name>` という構文を使用して、リンクに明示的なタイトルを付ける必要があります。

注意

参照ラベルはアンダースコアで始める必要があります。ラベルを参照する場合、アンダースコアを省略する必要があります（上記の例を参照）。

ファイル間で機能し、セクションの見出しが変更された場合に警告を発生させ、クロスリファレンスをサポートするすべてのビルダーで機能するため、セクションへの標準の reStructuredText リンク ( `Section title`_ など) よりも ref を使用することをお勧めします。

ドキュメントへのクロスリファレンス¶

バージョン 0.6 で追加されました。

ドキュメントに直接リンクする方法もあります。

:doc:¶

指定されたドキュメントへのリンク。ドキュメント名は絶対パスまたは相対パスで指定できます。たとえば、参照 :doc:`parrot` がドキュメント sketches/index にある場合、リンクは sketches/parrot を参照します。参照が :doc:`/people` または :doc:`../people` の場合、リンクは people を参照します。

明示的なリンクテキストが指定されていない場合（通常どおり：:doc:`Monty Python members </people>`）、リンクキャプションは指定されたドキュメントのタイトルになります。

ダウンロード可能なファイルの参照¶

バージョン 0.6 で追加されました。

:download:¶

このロールを使用すると、ソースツリー内で、表示可能な reStructuredText ドキュメントではなく、ダウンロード可能なファイルにリンクできます。

このロールを使用すると、参照されるファイルはビルド時に出力に含めるように自動的にマークされます（明らかに、HTML 出力の場合のみ）。すべてのダウンロード可能なファイルは、出力ディレクトリの _downloads/<unique hash>/ サブディレクトリに配置されます。重複するファイル名は処理されます。

例：

See :download:`this example script <../example.py>`.

指定されたファイル名は通常、現在のソースファイルが格納されているディレクトリからの相対パスですが、絶対パス（/ で始まる）の場合は、トップソースディレクトリからの相対パスと見なされます。

example.py ファイルが出力ディレクトリにコピーされ、適切なリンクが生成されます。

利用できないダウンロードリンクを表示しないようにするには、このロールを持つ段落全体を次のようにラップする必要があります。

.. only:: builder_html

   See :download:`this example script <../example.py>`.

図番号による図へのクロスリファレンス¶

バージョン 1.3 で追加されました。

バージョン 1.5 で変更されました: numref ロールはセクションも参照できます。また、numref では、リンクテキストに {name} を使用できます。

:numref:¶

指定された図、表、コードブロック、およびセクションへのリンク。標準の reStructuredText ラベルが使用されます。このロールを使用すると、「図 1.1」のように図番号によるリンクテキストを使用して、図への参照が挿入されます。

明示的なリンクテキストが指定されている場合（通常は :numref:`Image of Sphinx (Fig. %s) <my-figure>` のように）、リンクのキャプションが参照のタイトルとして使用されます。プレースホルダーとして、%s と {number} は図番号に、{name} は図のキャプションに置き換えられます。明示的なリンクテキストが指定されていない場合、numfig_format 設定がフォールバックのデフォルトとして使用されます。

numfig が False の場合、図には番号が付けられないため、このロールは参照ではなくラベルまたはリンクテキストを挿入します。

その他の項目の相互参照¶

以下のロールは、相互参照を作成する可能性がありますが、オブジェクトを参照しません

:confval:¶: 設定値または設定。索引エントリが生成されます。また、一致する confval ディレクティブが存在する場合は、それへのリンクも生成します。

:envvar:¶: 環境変数。索引エントリが生成されます。また、一致する envvar ディレクティブが存在する場合は、それへのリンクも生成します。

:token:¶: 文法トークンの名前（productionlist ディレクティブ間のリンクを作成するために使用されます）。

:keyword:¶: Python のキーワード名。これは、同じ名前の参照ラベルが存在する場合、それへのリンクを作成します。

:option:¶: 実行可能プログラムのコマンドラインオプション。これは、option ディレクティブが存在する場合、それへのリンクを生成します。

次のロールは、用語集内の用語への相互参照を作成します

:term:¶

用語集内の用語への参照。用語集は、用語と定義を含む定義リストを含む glossary ディレクティブを使用して作成されます。 term マークアップと同じファイルにある必要はありません。たとえば、Python のドキュメントには、glossary.rst ファイルにグローバルな用語集が1つあります。

用語集で説明されていない用語を使用すると、ビルド中に警告が表示されます。