ロール

Sphinx は、解釈済みテキストロールを使用して、ドキュメントにセマンティックマークアップを挿入します。これらは :rolename:`content` のように記述されます。

注記

デフォルトのロール (`content`) は、デフォルトでは特別な意味を持ちません。変数名など、自由に使用できます。default_role 設定値を使用して、既知のロールに設定できます。何かを見つけるには any ロール、Python オブジェクトを見つけるには py:obj ロールが非常に便利です。

ドメイン を参照して、ドメインによって追加されたロールを確認してください。

相互参照構文

相互参照構文 を参照してください。

相互参照ロールには以下が含まれます。

インラインコードの強調表示

:code:

インラインのコード例です。直接使用する場合、このロールは構文の強調表示なしで、リテラルとしてテキストを表示するだけです。

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

表示：デフォルトでは、1 + 2 などのインラインコードは、強調表示なしで表示されます。

code-block ディレクティブとは異なり、このロールは highlight ディレクティブによって設定されたデフォルトの言語を尊重しません。

構文の強調表示を有効にするには、最初に Docutils の role ディレクティブを使用して、特定の言語に関連付けられたカスタムロールを定義する必要があります。

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

複数行のコード例を表示するには、代わりに code-block ディレクティブを使用してください。

数式

:math:

インライン数式用のロール。次のように使用します。

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

表示：ピタゴラス以来、私たちは \(a^2 + b^2 = c^2\) を知っています。

:eq:

math:numref と同じです。

その他のセマンティックマークアップ

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

:abbr:

略語です。ロールの内容に括弧で囲まれた説明が含まれている場合、特別な扱いを受けます。HTML ではツールチップに表示され、LaTeX では一度だけ出力されます。

例：:abbr:`LIFO (last-in, first-out)` は LIFO と表示されます。

バージョン 0.6 で追加されました。

:command:

rm など、OS レベルのコマンドの名前です。

例：rm

:dfn:

テキスト内で用語の定義インスタンスをマークします。（インデックスエントリは生成されません。）

例：バイナリモード

:file:

ファイルまたはディレクトリの名前です。内容内では、波括弧を使用して「変数」部分を指定できます。例：

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

表示：… は /usr/lib/python3.x/site-packages にインストールされています…

作成されたドキュメントでは、x は、Python のマイナーバージョンに置き換えられることを示すために異なる方法で表示されます。

:guilabel:

インタラクティブなユーザーインターフェースの一部として提示されるラベルは、guilabel を使用してマークする必要があります。これには、curses またはその他のテキストベースのライブラリを使用して作成されたものなど、テキストベースのインターフェースからのラベルが含まれます。インターフェースで使用されるラベルはすべて、ボタンラベル、ウィンドウタイトル、フィールド名、メニューとメニュー選択名、さらには選択リストの値も含めて、このロールでマークする必要があります。

バージョン 1.0 で変更されました: GUI ラベルのアクセラレータキーをアンパサンドを使用して含めることができます。これは削除され、出力で下線付きで表示されます（例：:guilabel:`&Cancel` は Cancel と表示されます）。リテラルのアンパサンドを含めるには、2 つ重ねて使用します。

:kbd:

キーストロークのシーケンスをマークします。キーシーケンスの形式は、プラットフォームまたはアプリケーション固有の規則に依存する場合があります。関連する規則がない場合は、修飾キーの名前を明確に記述して、新しいユーザーや非ネイティブスピーカーのアクセシビリティを向上させる必要があります。たとえば、xemacs のキーシーケンスは :kbd:`C-x C-f` のようにマークできますが、特定のアプリケーションまたはプラットフォームを参照せずに、同じシーケンスは :kbd:`Control-x Control-f` としてマークする必要があります。それぞれ C-x C-f と Control-x Control-f と表示されます。

:mailheader:

RFC 822 スタイルのメールヘッダーの名前です。このマークアップは、ヘッダーがメールメッセージで使用されていることを意味するものではありませんが、同じ「スタイル」のヘッダーを参照するために使用できます。これは、さまざまな MIME 仕様で定義されているヘッダーにも使用されます。ヘッダー名は、通常どおりに入力する必要があります。複数のコモンユースがある場合は、キャメルケースの規則が優先されます。例：:mailheader:`Content-Type` は Content-Type と表示されます。

:makevar:

make 変数の名前です。

例：help

:manpage:

Unix マニュアルページへの参照（セクションを含む、例: :manpage:`ls(1)`）は、ls(1) と表示されます。manpages_url が定義されている場合、マニュアルページを表示する外部サイトへのハイパーリンクを作成します。

バージョン 7.3 で変更: ハイパーリンクのように、<> を使用してターゲットを指定できるようになりました。例えば、:manpage:`blah <ls(1)>` は blah と表示されます。

:menuselection:

メニュー選択は、menuselection ロールを使用してマークする必要があります。これは、サブメニューの選択や特定の操作の選択など、メニュー選択の完全なシーケンス、またはそのようなシーケンスの部分シーケンスをマークするために使用されます。個々の選択の名前は --> で区切る必要があります。

例えば、「開始 > プログラム」の選択をマークするには、次のマークアップを使用します。

:menuselection:`Start --> Programs`

表示：開始 ‣ プログラム

コマンドがダイアログを開くことを示すために一部のオペレーティングシステムで使用される省略記号など、末尾の指示子を含む選択を含める場合、指示子は選択名から省略する必要があります。

menuselection は、guilabel と同様に、アンパサンドアクセラレータもサポートします。

:mimetype:

MIME タイプの名前、または MIME タイプのコンポーネント（メジャーまたはマイナー部分のみ）。

例: text/plain

:newsgroup:

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

例: comp.lang.python

:program:

実行可能プログラムの名前。これは、プラットフォームによっては実行可能ファイル名と異なる場合があります。特に、Windows プログラムの場合、.exe（またはその他）の拡張子は省略する必要があります。

例: curl

:regexp:

正規表現。引用符を含める必要はありません。

例: ([abc])+

:samp:

コードなどのリテラルテキストの一部。内容内では、file のように、波括弧を使用して「変数」部分を指示できます。例えば、:samp:`print(1+{variable})` の場合、variable 部分は強調表示されます。print(1+variable)

「変数部分」の指示が必要ない場合は、代わりに標準の code ロールを使用してください。

バージョン 1.8 で変更: 二重バックスラッシュによる波括弧のエスケープが可能になりました。例えば、:samp:`print(f"answer=\\{1+{variable}*2\\}")` の場合、variable 部分は強調表示され、エスケープされた波括弧が表示されます。print(f"answer={1+variable*2}")

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

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

:pep:

Python Enhancement Proposal への参照。適切なインデックスエントリを生成します。「PEP 番号」というテキストが生成され、HTML 出力ではこのテキストは指定された PEP のオンラインコピーへのハイパーリンクになります。:pep:`number#anchor` とすることで、特定のセクションにリンクできます。

例: PEP 8

:rfc:

Internet Request for Comments への参照。適切なインデックスエントリを生成します。「RFC 番号」というテキストが生成され、HTML 出力ではこのテキストは指定された RFC のオンラインコピーへのハイパーリンクになります。:rfc:`number#anchor` とすることで、特定のセクションにリンクできます。

例: RFC 2324

標準の reStructuredText マークアップを使用できるため、ハイパーリンクを含めるための特別なロールはないことに注意してください。

置換

ドキュメントシステムは、デフォルトで定義されているいくつかの置換を提供します。これらはビルド設定ファイルで設定されます。

|release|

ドキュメントが参照するプロジェクトのリリースに置き換えられます。これは、アルファ/ベータ/リリース候補タグを含む完全なバージョン文字列を意味します（例: 2.5.2b3）。release によって設定されます。

|version|

ドキュメントが参照するプロジェクトのバージョンに置き換えられます。バージョン 2.5.1 の場合でも、メジャーバージョンとマイナーバージョン部分のみで構成されることを意図しています（例: 2.5）。version によって設定されます。

|today|

今日の日付（ドキュメントが読み取られた日付）またはビルド設定ファイルに設定された日付に置き換えられます。通常は April 14, 2007 の形式です。today_fmt と today によって設定されます。

|translation progress|

ドキュメントの翻訳進行状況に置き換えられます。この置換は、ドキュメント翻訳者がドキュメントの翻訳進行状況のマーカーとして使用する目的で意図されています。