クロスリファレンス文法¶
クロスリファレンスは、意味解釈済みのテキストロールから生成されます。基本的には :ロール:`用語` という形式で書くだけでクロスリファレンスを作成できます。このときは 用語 というアイテム名で、 ロール で指定されたタイプを持つリンクが作成されます。リンクに表示されるテキストは 用語 と同じになります。
追加の補助機能がいくつかありますが、これはロールに対するクロスリファレンスの目的を増やすものになります。:
:ロール:`タイトル <参照対象>`というreSTのハイパーリンクに似た書き方をすると、タイトルと参照対象の両方を明示できます。この場合は 参照対象 を参照するリンクになりますが、リンクテキストとして表示されるのは タイトル になります。用語の先頭の文字に
!を指定すると、参照もハイパーリンクも作成されなくなります。もし、先頭に
~が付けられると、ターゲットの最後の項目だけがリンクテキストになります。例えば、:py:meth:`~Queue.Queue.get`と書かれると、Queue.Queue.getを参照しますが、リンクテキストとして表示されるのは、getだけになります。これは全てのクロスリファレンスで動作するのではなく、ドメインでのみ動作します。HTML出力時には、リンクの
titleアトリビュート(マウスを上に持って行ったときにツールチップとして表示されるテキスト)には、常に、完全な参照対象の名前が設定されます。
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のインベントリからターゲットを探します。
オブジェクトのクロスリファレンス¶
これらのロールは、それぞれのドメインの中で説明されています。
自由な場所へのクロスリファレンス¶
- :ref:¶
標準のreSTのラベルを使用して、ドキュメント内の自由な位置にクロスリファレンスを作成することもできます。このラベルがきちんと動作するためには、ドキュメント全体の中で重複したラベルを使用することはできません。ラベルはユニークである必要があります。ラベルを参照する方法は２つあります:
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
refis 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:¶
このロールは表示可能なreST形式ではなく、ソースツリーに存在するその他の形式のファイルへのリンクを張って、ファイルをダウンロードできるようにするときに使用します。
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.
- :numref:¶
指定された図、表、コードブロック、セクションへの参照を作成します。ターゲットにはreSTのlabelを使用します。このロールを使用すると、"図 1.1"のようなリンクテキストを持つその図への参照が挿入されます。
リンクターゲットに明示的にキャプションを指定した場合(
:numref:`Sphinxの画像 (図. %s) <my-figure>`)、キャプションは表示用のテキストとして使用されます。 %s と {number} はプレースホルダーで、表示時に図表番号と {name} に置き換わります。リンクターゲットに明示的にキャプションが指定されなかった場合、デフォルトの設定としてnumfig_formatが使用されます。もし
numfigがFalseなら、図表番号は振られません。それなので、ロールは参照ではなく、ラベルか指定されたテキストを挿入します。
他の要素へのクロスリファレンス¶
以下のロールはクロスリファレンスを作成しますが、特定のオブジェクトを参照しません。
- :token:¶
文法のトークンの名前です。
productionlistディレクティブ内の定義との間でリンクが作成されます。
- :keyword:¶
Pythonのキーワード名です。もし存在していれば、この名前を持つ参照ラベルとの間にリンクが作成されます。
以下のロールは 用語集 との間にクロスリファレンスを作成します:
- :term:¶
用語集の用語への参照。用語集は
glossaryディレクティブを使用して定義します。用語集とtermマークアップは同じファイルにある必要はありません。例えばPythonのドキュメントは一つの用語集のglossary.rstというファイルの中にすべての用語の定義が書かれています。もしも、用語集の中で説明されていない用語がある場合には、ビルド時に警告が出力されます。