役柄

Sphinxは,解釈されたテキスト役割を用いて意味タグを文書に挿入する.彼らはこう書かれています :rolename:`content `.

注釈

デフォルトの役割 (`content )デフォルトでは特別な意味はありません。変数名のような任意の好きな用途に自由に使用することができます。 :confval:`default_role 構成値は既知のロールに設定されます。 any キャラクターは何かを探したり py:obj Pythonオブジェクトを探す役割は非常に有用です。

網域. ドメインごとに追加するための役割。

交差引用文法

交差引用は,多くの意味解釈のテキストの役割から生成される.基本的には書くだけで :role:`target `,名前の項目へのリンクが作成されます 目標 表示タイプの role それがそうです。リンクされたテキストは 目標 それがそうです。

しかし、クロス引用ロールをより汎用的にすることができる追加機能もある。

  • REST直接ハイパーリンクのように、明確なタイトルと引用目標を提供することができます。 :role:`title <target> `引用する 目標 しかしリンクテキストは タイトル それがそうです。

  • コンテンツの前に接頭辞をつけると ! 参照/ハイパーリンクは作成されません。

  • コンテンツの前に接頭辞をつけると ~ したがって,リンクテキストはターゲットの最後のコンポーネントのみとなる.例えば :py:meth:`~Queue.Queue.get 引用する ``Queue.Queue.get` しかし表示されているのは get リンクテキストとする.これはすべての交差参照ロールには適用されないが,ドメイン固有である.

    HTML出力では,リンクの title 属性(たとえば,マウスドロップ時にツール提示として表示される)は,つねに完全なターゲット名となる.

何でも交差して引用します

:any:

バージョン 1.3 で追加.

この便利な役割はその参照テキストのための効果的な目標を見つけるために努力している。

  • First, it tries standard cross-reference targets that would be referenced by doc, ref or 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モジュール(通常 `signal` または`` :mod:`signal )と1つの部分(通常 `about-signals` `)

♪the any 役はまだ intersphinx 拡張:ローカル照合が見つからない場合には,Intersphinx在庫のすべてのオブジェクトタイプも検索する.

交差引用対象

これらのロールは、それぞれのドメインを使用して説明される。

任意の位置を交差引用する

:ref:

どの文書中の任意の位置への交差参照をサポートするためには,標準RESTタグを用いる必要がある.そのため、ラベル名は文書全体で唯一でなければならない。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`.
    

    ♪the :ref: ロールはその後,その部分へのリンクを生成し,リンクタイトルは“交差引用する部分”である.これは,節と参照が異なるソースファイルにある場合にも有効である.

    自動ラベルはイラストにも適用される。例えば:

    .. _my-figure:
    
    .. figure:: whatever
    
       Figure caption
    

    本例では、参照 :ref:`my-figure `リンクテキスト“イラストタイトル”を持つイラストへの引用を挿入する.

    属性が明示的なヘッダを指定しているテーブルも同様である. table 指令する。

  • 節タイトルの前に置かれていないラベルを参照することもできるが、以下の文法を使用してリンクのための明確なタイトルを指定しなければならない: :ref:`Link title <label-name> `.

注釈

引用ラベルは以下の下線で始まる必要がある.ラベルを参照する際には,下線を省略しなければならない(上の例を参照).

Vbl.使用 ref 指向部分(たとえば)の標準reStruredTextリンクを使用することを提案する. `Section title`_ )は、ファイル間で動作することができるので、節タイトルが変更された場合、正しくなければ警告を発し、交差参照をサポートするすべてのビルダに適用される。

照合文書.

バージョン 0.6 で追加.

文書に直接リンクする方法もあります

:doc:

指定された文書にリンクします;文書名は絶対的または相対的に指定することができます。例えば引用すれば :doc:`parrot 文書に現れる ``sketches/index` このリンクとは sketches/parrot それがそうです。もし引用が :doc:`/people または`` :doc:`../people ,リンクとは ``people` それがそうです。

明確なリンクテキストが与えられていなければ(いつものように: :doc:`Monty Python members </people> `),リンクタイトルは与えられた文書のタイトルとなる.

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

バージョン 0.6 で追加.

:download:

この役割により、ソースツリー内のファイルにリンクすることができます。これらのファイルは、閲覧可能なRESTファイルではなく、ダウンロード可能なファイルです。

このロールを使用する場合、参照されたファイルは、生成時に出力に含まれるように自動的にマークされる(明らかに、HTML出力に限定される)。すべてのダウンロード可能なファイルを入れます _downloads/<unique hash>/ ディレクトリのサブディレクトリを出力する;重複するファイル名を処理する.

例::

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

所与のファイル名は、通常、現在のソースファイルが存在するディレクトリに対して相対的であるが、それが絶対である場合(これでは) / )であれば、上位ソースディレクトリに対するものとみなされる。

♪the example.py ファイルは出力ディレクトリにコピーされ,そのファイルへの適切なリンクが生成される.

利用不可能なダウンロードリンクを表示しないためには、このロールを持つ段落全体を改行する必要があります:

.. only:: builder_html

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

地物番号で地物を照合する

バージョン 1.3 で追加.

バージョン 1.5 で変更: numref 役割は各節を参考にすることもできる.と…。 numref 許す {{name}} テキストをリンクするために用いられる.

:numref:

指定された図形、テーブル、コードブロック、および部分にリンクし、標準RESTタグを使用します。この役割を使用する場合、“図1.1”のようなリンクテキスト付き図形への参照を図形番号で挿入します。

If an explicit link text is given (as usual: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {number} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the numfig_format setting is used as fall-back default.

もし numfig はい。 False ,図形には番号がないため,この役割は引用ではなく,ラベルやリンクテキストに挿入される.

他の興味のある項目を交差参考にする

以下の役割は交差引用を作成する可能性がありますが、オブジェクトを引用しません。

:envvar:

環境変数。インデックス項目を生成する.指向マッチングも生成されます envvar コマンド(存在すれば).

:token:

文法タグの名前( productionlist 指令)。

:keyword:

Pythonのキーワードの名前です。これは、その名前を有する参照タグを指すリンク(存在する場合)を作成する。

:option:

実行可能プログラムのコマンドラインオプション。これは指向を生成します option コマンド(存在すれば).

次の役割作成ペア glossary

:term:

語彙表中のタームへの引用語彙表は使っています glossary 命令は、用語および定義を有する定義リストを含む。それは必要ありません term Python文書のようなタグは glossary.rst ファイルです。

語彙表に説明されていない用語を使用した場合、構築中に警告を受けることになります。

数学.

:math:

数学の役割を果たしています使用方法は以下のとおりである.

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

相同 math:numref それがそうです。

その他の意味標識

以下のロールは、テキストを異なるスタイルでフォーマットする以外に、特別な動作は実行しません。

:abbr:

略語です。ロール内容に括弧付き解釈が含まれている場合には,HTML形式でツール提示に表示され,LaTeX形式で1回のみ出力される特殊な処理が行われる.

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

バージョン 0.6 で追加.

:command:

オペレーティングシステムレベルのコマンドの名前、例えば rm それがそうです。

:dfn:

タグ付きテキスト中のタームの定義事例(インデックス項目は生成されません。)

:file:

ファイルまたはディレクトリの名前。コンテンツでは、大きな括弧を使用して“可変”部分を表すことができます。例えば、:

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

構築された文書では x Pythonの副次的なバージョンに置き換えられることを示すために、異なる方法で表示されます。

:guilabel:

インタラクティブなユーザインタフェースの一部として表示されるタグは使用すべきである guilabel それがそうです。これは、テキストベースのインタフェース(例えば、作成されたインタフェースを使用する)からのタグを含む curses テキストベースの他のライブラリですインタフェースで使用される任意のタグは、ボタンタグ、ウィンドウタイトル、フィールド名、メニューおよびメニュー選択名、さらにはリスト内の値を選択することを含むロールとしてマークされるべきである。

バージョン 1.0 で変更: GUIタグを含むAND番号のショートカットキーを使用することができ、剥離され、出力中に下線を付して表示される(例えば、: :guilabel:`&Cancel `)文字と番号が含まれている場合は、それを2倍にしてください。

:kbd:

一連の打鍵をマークする.キーシーケンスがどのような形態をとるかは、プラットフォームまたはアプリケーションに固有の約束に依存する可能性がある。関連する約束がない場合には,新規ユーザと非母国語利用者のアクセス可能性を向上させるために,修飾キーの名前をスペルすべきである.例えば1つは Xemacs キーシーケンスは以下のように表記することができる. :kbd:`C-x C-f しかし,特定のアプリケーションやプラットフォームを参照しない場合,同じシーケンスはラベル付けされるべきである. `Control-x Control-f` `.

:mailheader:

RFC 822スタイルのヘッダの名前です。このタグは、電子メールメッセージにタイトルが使用されているわけではないが、同じ“スタイル”の任意のタイトルを参照するために使用されてもよい。これは、様々なMIME仕様定義のヘッダにも使用される。ヘッダ名の入力方式は,実際に一般的に使用される方式と同様であるべきであり,複数の一般的な用法がある場合には,こぶサイズの約定を用いることが望ましい.例: :mailheader:`Content-Type `.

:makevar:

の名称 make 変数です。

:manpage:

部分を含むUnixマニュアルページへの参照、例えば :manpage:`ls(1) .以下の場合は,マニュアルページを提示する外部サイトへのハイパーリンクを作成する. :confval:`manpages_url 定義されています

:menuselection:

メニューオプションは使用する必要があります menuselection 役。これは、サブメニューの選択および特定の動作の選択、またはそのようなシーケンスの任意のサブシーケンスを含む完全なメニュー選択シーケンスをマークするために使用される。各選択の名称は --> それがそうです。

例えば、選択タグを“Start>Programs”と表記するには、以下のタグを使用してください。

:menuselection:`Start --> Programs`

いくつかの付随インジケータを含む選択が含まれている場合、例えば、いくつかのオペレーティングシステムは、コマンドがダイアログの省略番号を開くことを示すために使用され、インジケータは、選択された名前から省略されるべきである。

menuselection 記号加速器にも対応しています guilabel それがそうです。

:mimetype:

MIMEタイプの名前またはMIMEタイプのコンポーネント(主要部分またはサブ部分、単独で使用)

:newsgroup:

Usenetニュースグループの名前。

課題

これは標準域の一部ではありませんか。

:program:

実行可能プログラムの名前.これは、いくつかのプラットフォームの実行可能ファイルのファイル名とは異なる可能性がある。特に、 .exe Windowsプログラムについては、拡張子は省略(またはその他)すべきである。

:regexp:

正規表現.引用符を含めてはいけません。

:samp:

コードのような文字テキストですコンテンツでは、大きな括弧を使って“可変”部分を表すことができます。 file それがそうです。例えばここでは :samp:`print 1+{{variable}} この部分は ``variable` 強調されます。

“可変部品”の指示が必要でない場合は、基準をご利用ください ``code 代わりに``

バージョン 1.8 で変更: 逆スラッシュの使用許可大括弧

一つもあります index ロールはインデックス項目を生成する.

以下の役割は外部リンクを生成する:

:pep:

Python拡張プログラムへの参照。これにより,適切なインデックス項目が生成される.テキスト“PEP” 番号をつける 生成“;HTML出力では,このテキストはPEPのオンラインコピーを指定するハイパーリンクである.以下のように特定の部分にリンクすることができます :pep:`number#anchor `.

:rfc:

Internetに対するコメントの参照を要求する.これにより,適切なインデックス項目が生成される.テキスト“RFC” 番号をつける “生成;HTML出力では,このテキストはRFCのオンラインコピーを指定するハイパーリンクである.以下のように特定の部分にリンクすることができます :rfc:`number#anchor `.

標準RESTタグを使用してこの目的を達成することができるので、ハイパーリンクを含むための特別なロールは存在しないことに注意されたい。

代わる

文書システムは、デフォルトで定義された3つの置換を提供する。これらは、生成プロファイルに設定されています。

|release|

文書が指す項目バージョンに置き換える.これは、例えば、Alpha/Beta/Release候補タグを含む完全なバージョンの文字列を意味する 2.5.2b3 それがそうです。設置者 release それがそうです。

|version|

文書参照の項目バージョンに置き換える.これは、例えば、主要バージョンおよび第2のバージョン部分のみが含まれることを意味する 2.5 バージョン2.5.1についても同様である。設置者 version それがそうです。

|today|

今日の日付(文書を読み取る日)に置き換えるか、プロファイルに設定された日付を生成します。通常以下の形式を持つ April 14, 2007 それがそうです。設置者 today_fmt そして today それがそうです。