Sphinxは解釈済みのテキストのロールというものを使用して、用語の意味を記述して、リンクを張ったりすることができます。これを記述する時は :ロール名:`内容` というフォーマットで記述します。
Note
デフォルトのロール(`content`)には標準では特別な意味を持っていません。必要に応じてどのように使用してもかまいません。例えば変数名として使用する、などです。 default_role という設定値を変更することで、デフォルトのロールに対して、既存のロールを設定することができます。
ドメインによって追加される追加のロールに関しては Sphinxドメイン を参照してください。
クロスリファレンスは、意味解釈済みのテキストロールから生成されます。基本的には :ロール:`用語` という形式で書くだけでクロスリファレンスを作成することができます。このときは 用語 というアイテム名で、 ロール で指定されたタイプを持つリンクが作成されます。リンクに表示されるテキストは 用語 と同じになります。
追加の補助機能がいくつかありますが、これはロールに対するクロスリファレンスの目的を増やすものになります。:
用語の先頭の文字に ~ を設定すると、リンクテキストは最後の項目だけが表示されるようになります。例えば、 :py:meth:`~Queue.Queue.get` というマークアップがあったとすると、 Queue.Queue.get に対して参照が作成されますが、リンクテキストとしては get が表示されます。
HTML出力時には、リンクの title アトリビュート(マウスを上に持って行ったときにツールチップとして表示されるテキスト)には、常に、完全な参照対象の名前が設定されます。
標準のreSTのラベルを使用して、ドキュメント内の自由な位置にクロスリファレンスを作成することもできます。このラベルがきちんと動作するためには、ドキュメント全体の中で重複したラベルを使用することはできません。ラベルはユニークである必要があります。ラベルを参照する方法は２つあります:
セクションのタイトルの直前にラベルを置くと、 :ref:`label-name` と書くことで参照できるようになります:
.. _my-reference-label:
クロスリファレンスのセクション
------------------------------
これはセクションのテキストです。
これはセクションそのものを参照します。 :ref:`my-reference-label`
:ref: ロールはセクションへのリンクを作成します。リンクのタイトルは “クロスリファレンスのセクション” になります。この機能はセクションと参照が異なるソースファイルにあるときに動作します。
自動ラベルは図に対しても動作します:
.. _my-figure:
.. figure:: whatever
図のキャプション
:ref:`my-figure` 参照を書くと、 “図のキャプション” というテキストを持つ、図への参照が生成されます。
table ディレクティブを使用して、キャプションを明示しているテーブルに対しても、同様の働きをします。
これはファイルをまたいで動作するため、セクションの表題が変更されると、 ref を使用する、標準のreStructuredTextのセクション( `セクションタイトル`_ )へのリンクに対して通知されます。これはクロスリファレンスをサポートするすべてのビルダーについて言えます。
New in version 0.6.
ドキュメントに対して直接リンクを張る方法もあります。
絶対/相対のどちらかの形式でドキュメント名を指定することで、特定のドキュメントに対してリンクを張ることができます。例えば、 :doc:`parrot` という参照が sketches/index というファイルの中にあったとすると、 skethes/parrot に対するリンクとなります。もし参照が :doc:`/people` もしくは :doc:`../people` という形式で書かれている場合には people に対するリンクが作成されます。
:doc:`Monty Python members </people>` という形式で、明示的にリンクテキストを指定することができますが、もし明示的なリンクテキストが与えられなかった場合には指定されたドキュメントのタイトルがリンクテキストとなります。
New in version 0.6.
このロールは表示可能なreST形式ではなく、ソースツリーに存在するその他の形式のファイルへのリンクを張って、ファイルをダウンロードできるようにするときに使用します。
このロールを使用すると、HTML出力時に、参照されたファイルはビルド時に自動的に出力ディレクトリにコピーされることになります。すべてのダウンロード可能なファイルは出力ディレクトリ中の _downloads サブディレクトリ出力されます。重複した名前のファイルがあっても扱うことができます。
サンプル:
:download:`このサンプルスクリプト <../example.py>` を参照してください
与えられたファイル名は通常、そのロールが書かれているソースファイルからの相対ディレクトリで指定されますが、もし絶対パス(/ で始まる)の場合には、トップのソースディレクトリからの相対パスとして見られます。
example.py ファイルは出力ディレクトリにコピーされ、適切なリンクが生成されます。
以下のロールは、テキストのスタイルを変更する意外には特別なことはしません。
言葉の短縮形を書くのに使用します。ロールの中身として、括弧付き表現が含まれていた場合には特別扱いされます。HTMLではツールチップとして使用され、LaTeXでは一度だけ出力されます。
例: :abbr:`LIFO (last-in, first-out)`.
New in version 0.6.
rm のような、OSレベルのコマンドの名前に使用します。
テキスト中の用語の定義を書くのに使用します。インデックスエントリーは作成されません。
ファイルやディレクトリの名前に使用します。ロールの中身の中には”変数”を表す波括弧を含めることができます。例:
... は :file:`/usr/lib/python2.{x}/site-packages` にインストールされます ...
ドキュメントのビルドの中で、 x Pythonのマイナーバージョンを表す文字に置き換えられて表示されます。
インタラクティブなユーザインタフェースの一部のラベルとして表示される文字に対しては guilabel を使用します。これは、 curses やその他のコンソール用ライブラリを使用したテキストベースのインタフェースにも使用します。ボタンやウィンドウのタイトル、フィールド名、メニュー、やメニューの項目名、リスト中の選択された値など、インタフェース上に表示されるラベルには、このロールを使用すべきです。
Changed in version 1.0.
キーボード操作のキーに使用します。 キー操作をどのように表現するかはプラットフォームや、アプリケーション上の慣習の影響を受けます。もし、慣習に関しての制約がない場合には、修飾キー(Shiftなど)の名前は、省略せずにきちんと書くと、新規ユーザと、英語がネイティブでないユーザから見たアクセシビリティは向上します。例えば、*xemacs* キー操作は :kbd:`C-x C-f` という表現になるでしょう。しかし、特定のアプリケーションやプラットフォームに限定する必要がなければ同じ操作は :kbd:`Control-x Control-f` と書くべきです。
RFC 822の形式のメールヘッダの名前に使用します。これでマークアップされたヘッダは電子メールのメッセージの中で必ず使用されている必要はありませんが、参照するのに他のヘッダと同じ形式を使用することが可能です。このヘッダはさまざまなMIMEの使用で定義されたヘッダに対しても使用することができます。ヘッダ名は実際に電子メール内で使用されるのと同じ形式(キャメルケース)で書かれるべきです。例えば、 :mailheader:`Content-Type` という形式になります。
make の変数名です。
セクションの内容を含むUnixのマニュアルページへの参照です。 例: :manpage:`ls(1)`
メニュー選択は menuselection ロールを使用すべきです。これはメニュー操作の手順をマークアップするのに使用します。メニューにはメニュー選択、サブメニュー選択、特定の操作での選択や、さらに細かいサブ操作などを含みます。それぞれの選択要素の名前は --> を使用して分割すべきです。
例えば、”スタート > プログラム”という順番でメニューを選択する動作は以下のように記述します:
:menuselection:`スタート --> プログラム`
もし、選択したメニューにはオペレーティングシステム固有のコマンドの指示などが含まれていた場合には、これは省略すべきです。例えば、ダイアログを開くコマンドなどです。このようなコマンドの指示は選択名からは省きます。
menuselection は guilabel と同じく、アンパサンドを利用したアクセラレータの表示に対応しています。
MIMEタイプの名前、もしくはの一部MIMEタイプ(メジャー、マイナー部分、もしくは単独)を表します。
USENETのニュースグループ名です。
実行プログラムの名前です。これはプラットフォームによって名前が変化することもあります。特にWindowsのプログラムのための .exe やそれ以外の拡張子はは省略すべきです。
正規表現です。引用符は含めることはできません。
リテラルのテキストの一部です。マークアップの内容の中には、 file と同様に波括弧を使った”変数”を書くことができます。たとえば、 :samp:`print 1+{variable}` というテキストがあると、 variable の部分が強調されます。
もし”変数部分”が不要であれば、標準の ``コード`` という形式を代わりに使用してください。
下記のロールは外部へのリンクを生成します。
Python拡張提案書(PEP)への参照です。これは適切なインデックスのエントリーを作成します。”PEP number“という形式のテキストが作成されます。HTML出力ではこのテキストは特定のPEPのオンラインのコピーへのハイパーリンクとなります。
インターネットのRFCへの参照です。これは適切なインデックスのエントリーを作成します。”RFC number“という形式のテキストが作成されます。HTML出力ではこのテキストは特定のRFCのオンラインのコピーへのハイパーリンクとなります。
このような目的を達成しようとしても、標準のreSTマークアップだけではハイパーリンクを取り込む特別なロールは存在しません。
以下のロールはクロスリファレンスを作成しますが、特定のオブジェクトを参照しません。
文法のトークンの名前です。 productionlist ディレクティブ内の定義との間でリンクが作成されます。
Pythonのキーワード名です。もし存在していれば、この名前を持つ参照ラベルとの間にリンクが作成されます。
実行ファイルのコマンドラインオプションです。前に付くハイフンも含める必要があります。 cmdoption ディレクティブで定義されていれば、リンクを作成します。
以下のロールは用語集との間にクロスリファレンスを作成します:
用語集の用語への参照。用語集は glossary ディレクティブを使用して定義します。用語集と term マークアップは同じファイルにある必要はありません。例えばPythonのドキュメントは一つの用語集の glossary.rst というファイルの中にすべての用語の定義が書かれています。
もしも、用語集の中で説明されていない用語がある場合には、ビルド時に警告が出力されます。
デフォルトでは3つの代数がドキュメントシステムから提供されています。これらはビルドの設定ファイルの中で設定されます。
ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、 2.5.2b3 などのような、alpha/beta/release candidateタグも含めた完全なバージョン文字列と置換されます。 release を使って設定します。
ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、メジャーバージョン、マイナーバージョンの定義部分のみを含む文字列です。例えば、``2.5.1`` というのがあったとすると、 2.5 になります。 version を使って設定します。