Cross-references¶

One of Sphinx's most useful features is creating automatic cross-references through semantic cross-referencing roles. A cross reference to an object description, such as :func:`spam`, will create a link to the place where spam() is documented, appropriate to each output format (HTML, PDF, ePUB, etc.).

Syntax¶

Sphinx supports various cross-referencing roles to create links to other elements in the documentation. In general, writing :role:`target` creates a link to the object called target of the type indicated by role. The link's text depends the role but is often the same as or similar to target.

The behavior can be modified in the following ways:

Custom link text: You can specify the link text explicitly using the same notation as in reStructuredText external links: :role:`custom text <target>` will refer to target and display custom text as the text of the link.
Suppressed link: Prefixing with an exclamation mark (!) prevents the creation of a link but otherwise keeps the visual output of the role.

For example, writing :py:func:`!target` displays target(), with no link generated.

This is helpful for cases in which the link target does not exist; e.g. changelog entries that describe removed functionality, or third-party libraries that don't support intersphinx. Suppressing the link prevents warnings in nitpicky mode.
Modified domain reference: When referencing domain objects, a tilde ~ prefix shortens the link text to the last component of the target. For example, :py:meth:`~queue.Queue.get` will refer to queue.Queue.get but only display get as the link text.

HTML出力時には、リンクの title アトリビュート(マウスを上に持って行ったときにツールチップとして表示されるテキスト)には、常に、完全な参照対象の名前が設定されます。

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

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

自由な場所へのクロスリファレンス¶

:ref:¶

To support cross-referencing to arbitrary locations in any document, the standard reStructuredText labels are used. For this to work label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels:

If you place a label directly before a section title, you can reference to it with :ref:`label-name`. For example:
```
.. _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: ロールはセクションへのリンクを作成します。リンクのタイトルは "クロスリファレンスのセクション" になります。この機能はセクションと参照が異なるソースファイルにあるときに動作します。

Automatic labels also work with figures. For example:
```
.. _my-figure:

.. figure:: whatever

   Figure caption
```
In this case, a reference :ref:`my-figure` would insert a reference to the figure with link text "Figure caption".

table ディレクティブを使用して、キャプションを明示しているテーブルに対しても、同様の働きをします。
セクションタイトルの前にないラベルに対しても参照することはできますが、タイトルを明示する必要があります。この場合には :ref:`リンクラベル <ラベル名>` という文法を使用します。

注釈

参照ラベルはアンダースコアで始まる必要があります。ラベルを参照するときには、先頭のアンダースコアは取り除く必要があります(上の例を参照)。

Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, will raise warnings if incorrect, and works for all builders that support cross-references.

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

Added in version 0.6.

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

:doc:¶

絶対/相対のどちらかの形式でドキュメント名を指定することで、特定のドキュメントに対してリンクを張ることができます。例えば、 :doc:`parrot` という参照が sketches/index というファイルの中にあったとすると、 sketches/parrot に対するリンクとなります。もし参照が :doc:`/people` もしくは :doc:`../people` という形式で書かれている場合には people に対するリンクが作成されます。

:doc:`Monty Python members </people>` という形式で、明示的にリンクテキストを指定できますが、もし明示的なリンクテキストが与えられなかった場合には指定されたドキュメントのタイトルがリンクテキストとなります。

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

Added in version 0.6.

:download:¶

This role lets you link to files within your source tree that are not reStructuredText documents that can be viewed, but files that can be downloaded.

When you use this role, the referenced file is automatically marked for inclusion in the output when building (obviously, for HTML output only). All downloadable files are put into a _downloads/<unique hash>/ subdirectory of the output directory; duplicate filenames are handled.

サンプル:

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

与えられたファイル名は通常、そのロールが書かれているソースファイルからの相対ディレクトリで指定されますが、もし絶対パス(/ で始まる)の場合には、トップのソースディレクトリからの相対パスとして見られます。

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

ダウンロードリンクが利用できないときに表示を切るには、段落全体をこのロールで囲う必要があります:

.. only:: builder_html

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

図表番号クロスリファレンス¶

Added in version 1.3.

バージョン 1.5 で変更: numref role can also refer sections. And numref allows {name} for the link text.

:numref:¶

Link to the specified figures, tables, code-blocks and sections; the standard reStructuredText labels are used. When you use this role, it will insert a reference to the figure with link text by its figure number like "Fig. 1.1".

リンクターゲットに明示的にキャプションを指定した場合(:numref:`Sphinxの画像 (図. %s) <my-figure>`)、キャプションは表示用のテキストとして使用されます。 %s と {number} はプレースホルダーで、表示時に図表番号と {name} に置き換わります。リンクターゲットに明示的にキャプションが指定されなかった場合、デフォルトの設定として numfig_format が使用されます。

もし numfig が False なら、図表番号は振られません。それなので、ロールは参照ではなく、ラベルか指定されたテキストを挿入します。

他の要素へのクロスリファレンス¶

以下のロールはクロスリファレンスを作成しますが、特定のオブジェクトを参照しません。

:confval:¶: A configuration value or setting. Index entries are generated. Also generates a link to the matching confval directive, if it exists.

:envvar:¶: 環境変数です。エントリーのインデックスが作成されます。もし envvar ディレクティブがあれば、それへのリンクが作成されます。

:token:¶: 文法のトークンの名前です。 productionlist ディレクティブ内の定義との間でリンクが作成されます。

:keyword:¶: Pythonのキーワード名です。もし存在していれば、この名前を持つ参照ラベルとの間にリンクが作成されます。

:option:¶: 実行ファイルのコマンドラインオプションです。 option ディレクティブが定義されていれば、リンクを作成します。

以下のロールは用語集との間にクロスリファレンスを作成します:

:term:¶

用語集の用語への参照。用語集は glossary ディレクティブを使用して定義します。用語集と term マークアップは同じファイルにある必要はありません。例えばPythonのドキュメントは一つの用語集の glossary.rst というファイルの中にすべての用語の定義が書かれています。

もしも、用語集の中で説明されていない用語がある場合には、ビルド時に警告が出力されます。

This role also supports custom link text from the general cross-reference syntax.

anyクロスリファレンス¶

:any:¶

Added in version 1.3.

この便利なロールは、参照先ターゲットを自動的に探してくれます。

最初に、標準のクロスリファレンス doc, ref, option として解釈できるか試してみます。

Custom objects added to the standard domain by extensions (see Sphinx.add_object_type()) are also searched.
次に、使われている全てのドメインのオブジェクト(ターゲット)に参照できるか試します。ターゲットが各ドメインで何にマッチするかの判定は各ドメインに任されています。例えば、Pythonドメインでは :any:`Builder` は sphinx.builders.Builder クラスにマッチします。

もし、ターゲットが見つからない、または複数のターゲットが見つかった場合、警告が出力されます。複数のターゲットが見つかった場合は"any"ではなく明示的にロールを指定してください。

This role is a good candidate for setting default_role. If you do, you can write cross-references without a lot of markup overhead. For example, in this Python function documentation:

.. 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のインベントリからターゲットを探します。