ロール

Sphinxは解釈済みのテキストのロールというものを使用して、用語の意味を記述して、リンクを張ったりできます。これを記述する時は :ロール名:`内容` というフォーマットで記述します。

注釈

デフォルトのロール(`content`)は標準では特別な意味を持っていません。必要に応じてどのように使用してもかまいません。例えば変数名として使用する、などです。設定値 default_role を設定すれば、デフォルトのロールに対して、既存のロールを指定できます。例えば、 any ロールは、任意のロールか、 py:obj ロールによるPythonオブジェクトを見つけられるため、デフォルトロールに設定するのに非常に有用です。

See Domains for roles added by domains.

クロスリファレンス文法

クロスリファレンスは、意味解釈済みのテキストロールから生成されます。基本的には :ロール:`用語` という形式で書くだけでクロスリファレンスを作成できます。このときは 用語 というアイテム名で、 ロール で指定されたタイプを持つリンクが作成されます。リンクに表示されるテキストは 用語 と同じになります。

追加の補助機能がいくつかありますが、これはロールに対するクロスリファレンスの目的を増やすものになります。:

• :ロール:`タイトル <参照対象>` というreSTのハイパーリンクに似た書き方をすると、タイトルと参照対象の両方を明示できます。この場合は 参照対象 を参照するリンクになりますが、リンクテキストとして表示されるのは タイトル になります。

• 用語の先頭の文字に ! を指定すると、参照もハイパーリンクも作成されなくなります。

• もし、先頭に ~ が付けられると、ターゲットの最後の項目だけがリンクテキストになります。例えば、 :py:meth:`~Queue.Queue.get` と書かれると、 Queue.Queue.get を参照しますが、リンクテキストとして表示されるのは、 get だけになります。これは全てのクロスリファレンスで動作するのではなく、ドメインでのみ動作します。

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

anyクロスリファレンス

:any:

バージョン 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"ではなく明示的にロールを指定してください。

このロールが適した候補を見つけるために 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のインベントリからターゲットを探します。

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

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

• Python

• C

• C++

• JavaScript

• ReST

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

: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 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.

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

バージョン 0.6 で追加.

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

:doc:

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

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

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

バージョン 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>`.

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

バージョン 1.3 で追加.

バージョン 1.5 で変更: numref ロールもセクションを参照します。 numref は {name} と書くことでリンクテキストを書くことも出来ます。

:numref:

指定された図、表、コードブロック、セクションへの参照を作成します。ターゲットにはreSTのlabelを使用します。このロールを使用すると、"図 1.1"のようなリンクテキストを持つその図への参照が挿入されます。

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

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

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

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

:envvar:

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

:token:

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

:keyword:

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

:option:

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

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

:term:

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

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

Math

:math:

インラインの数式のロールです。以下のようにして使用します:

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

:eq:

Same as math:numref.

上記以外の意味のマークアップ

以下のロールは、テキストのスタイルを変更する以外には特別なことはしません。

:abbr:

言葉の短縮形を書くのに使用します。ロールの中身として、括弧付き表現が含まれていた場合には特別扱いされます。HTMLではツールチップとして使用され、LaTeXでは一度だけ出力されます。

例: :abbr:`LIFO (last-in, first-out)`.

バージョン 0.6 で追加.

:command:

rm のような、OSレベルのコマンドの名前に使用します。

:dfn:

テキスト中の用語の定義を書くのに使用します。インデックスエントリーは作成されません。

:file:

ファイルやディレクトリの名前に使用します。ロールのコンテンツ部分には波括弧を使って"変数"を表すことができます。例:

... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...

ビルド後のドキュメントの中で、変数 x は Python のマイナーバージョンに置き換えられることを示すよう、強調表示されます。

:guilabel:

インタラクティブなユーザインタフェースの一部のラベルとして表示される文字に対しては guilabel を使用します。これは、 curses やその他のコンソール用ライブラリを使用したテキストベースのインタフェースにも使用します。ボタンやウィンドウのタイトル、フィールド名、メニュー、やメニューの項目名、リスト中の選択された値など、インタフェース上に表示されるラベルには、このロールを使用すべきです。

バージョン 1.0 で変更: GUIラベルにショートカットキーを設定するためにアンド記号を使用できます。この記号は表示されず代わりに下線が表示されます(例えばこのように書きます :guilabel:`&Cancel`)。アンド記号をそのまま表示したい場合は2つ書いてください。

:kbd:

キーボード操作のキーに使用します。 キー操作をどのように表現するかはプラットフォームや、アプリケーション上の慣習の影響を受けます。もし、慣習に関しての制約がない場合には、修飾キー(Shiftなど)の名前は、省略せずにきちんと書くと、新規ユーザと、英語がネイティブでないユーザから見たアクセシビリティは向上します。例えば、xemacs キー操作は :kbd:`C-x C-f` という表現になるでしょう。しかし、特定のアプリケーションやプラットフォームに限定する必要がなければ同じ操作は :kbd:`Control-x Control-f` と書くべきです。

:mailheader:

RFC 822の形式のメールヘッダの名前に使用します。これでマークアップされたヘッダは電子メールのメッセージの中で必ず使用されている必要はありませんが、参照するのに他のヘッダと同じ形式を使用することが可能です。このヘッダはさまざまなMIMEの使用で定義されたヘッダに対しても使用できます。ヘッダ名は実際に電子メール内で使用されるのと同じ形式(キャメルケース)で書かれるべきです。例えば、 :mailheader:`Content-Type` という形式になります。

:makevar:

make の変数名です。

:manpage:

セクションの内容を含むUnixのマニュアルページへの参照です。 例: :manpage:`ls(1)`。 manpages_url が定義されていたら、マニュアルページの内容が載っている外部サイトへのハイパーリンクを作成します。

:menuselection:

メニュー選択は menuselection ロールを使用すべきです。これはメニュー操作の手順をマークアップするのに使用します。メニューにはメニュー選択、サブメニュー選択、特定の操作での選択や、さらに細かいサブ操作などを含みます。それぞれの選択要素の名前は --> を使用して分割すべきです。

例えば、"スタート > プログラム"という順番でメニューを選択する動作は以下のように記述します:

:menuselection:`Start --> Programs`

もし、選択したメニューにはオペレーティングシステム固有のコマンドの指示などが含まれていた場合には、これは省略すべきです。例えば、ダイアログを開くコマンドなどです。このようなコマンドの指示は選択名からは省きます。

menuselection は guilabel と同じく、アンパサンドを利用したアクセラレータの表示に対応しています。

:mimetype:

MIMEタイプの名前、もしくはの一部MIMEタイプ(メジャー、マイナー部分、もしくは単独)を表します。

:newsgroup:

USENETのニュースグループ名です。

課題

これは標準ドメインの一部ではありませんか?

:program:

実行プログラムの名前です。これはプラットフォームによって名前が変化することもあります。特にWindowsのプログラムのための .exe やそれ以外の拡張子はは省略すべきです。

:regexp:

正規表現です。引用符は含めることはできません。

:samp:

リテラルのテキストの一部です。マークアップの内容の中には、 file と同様に波括弧を使った"変数"を書くことができます。たとえば、 :samp:`print 1+{variable}` というテキストがあると、 variable の部分が強調されます。

もし"変数部分"が不要であれば、標準の ``コード`` という形式を代わりに使用してください。

バージョン 1.8 で変更: Allowed to escape curly braces with backslash

インデックスのエントリーを生成するための、 index ロールもあります。

下記のロールは外部へのリンクを生成します。

:pep:

Python拡張提案書(PEP)への参照です。これは適切なインデックスのエントリーを作成します。"PEP number"という形式のテキストが作成されます。HTML出力ではこのテキストは特定のPEPのオンラインのコピーへのハイパーリンクとなります。特定の節にリンクするには :pep:`number#anchor` とします。

:rfc:

インターネットのRFCへの参照です。これは適切なインデックスのエントリーを作成します。"RFC number"という形式のテキストが作成されます。HTML出力ではこのテキストは特定のRFCのオンラインのコピーへのハイパーリンクとなります。特定の節にリンクするには :rfc:`number#anchor` とします。

このような目的を達成しようとしても、標準のreSTマークアップだけではハイパーリンクを取り込む特別なロールは存在しません。

置換

デフォルトでは3つの代数がドキュメントシステムから提供されています。これらはビルドの設定ファイルの中で設定されます。

|release|

ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、 2.5.2b3 などのような、alpha/beta/release candidateタグも含めた完全なバージョン文字列と置換されます。 release を使って設定します。

|version|

ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、メジャーバージョン、マイナーバージョンの定義部分のみを含む文字列です。例えば、2.5.1 というのがあったとすると、 2.5 になります。 version を使って設定します。

|today|

本日の日付に置き換えられます。日付はドキュメントが読み込まれた日になります。もしくはビルド設定ファイルにて日付を設定することも可能です。通常は April 14, 2007 というフォーマットが使用されます。 today_fmt と today を設定することで変更できます。