ロール

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

注釈

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

See Domains for roles added by domains.

クロスリファレンス文法

See クロスリファレンス文法.

Cross-reference roles include:

Inline code highlighting

:code:

An inline code example. When used directly, this role just displays the text without syntax highlighting, as a literal.

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

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

Unlike the code-block directive, this role does not respect the default language set by the highlight directive.

To enable syntax highlighting, you must first use the Docutils role directive to define a custom role associated with a specific language:

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

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

To display a multi-line code example, use the code-block directive instead.

Math

:math:

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

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

Displays: Since Pythagoras, we know that \(a^2 + b^2 = c^2\).

:eq:

Same as math:numref.

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

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

:abbr:

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

For example: :abbr:`LIFO (last-in, first-out)` displays LIFO.

Added in version 0.6.

:command:

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

For example: rm

:dfn:

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

For example: binary mode

:file:

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

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

Displays: ... is installed in /usr/lib/python3.x/site-packages ...

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

:guilabel:

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

バージョン 1.0 で変更: An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (for example: :guilabel:`&Cancel` displays Cancel). To include a literal ampersand, double it.

:kbd:

Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like :kbd:`C-x C-f`, but without reference to a specific application or platform, the same sequence should be marked as :kbd:`Control-x Control-f`, displaying C-x C-f and Control-x Control-f respectively.

:mailheader:

The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same "style." This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example: :mailheader:`Content-Type` displays Content-Type.

:makevar:

make の変数名です。

For example: help

:manpage:

A reference to a Unix manual page including the section, e.g. :manpage:`ls(1)` displays ls(1). Creates a hyperlink to an external site rendering the manpage if manpages_url is defined.

バージョン 7.3 で変更: Allow specifying a target with <>, like hyperlinks. For example, :manpage:`blah <ls(1)>` displays blah.

:menuselection:

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

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

:menuselection:`Start --> Programs`

Displays: Start ‣ Programs

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

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

:mimetype:

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

For example: text/plain

:newsgroup:

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

For example: comp.lang.python

課題

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

:program:

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

For example: curl

:regexp:

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

For example: ([abc])+

:samp:

A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a "variable" part, as in file. For example, in :samp:`print(1+{variable})`, the part variable would be emphasized: print(1+variable)

If you don't need the "variable part" indication, use the standard code role instead.

バージョン 1.8 で変更: Allowed to escape curly braces with double backslash. For example, in :samp:`print(f"answer=\\{1+{variable}*2\\}")`, the part variable would be emphasized and the escaped curly braces would be displayed: print(f"answer={1+variable*2}")

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

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

:pep:

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

For example: PEP 8

:rfc:

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

For example: RFC 2324

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

置換

The documentation system provides some substitutions that are defined by default. They are set in the build configuration file.

|release|

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

|version|

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

|today|

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

|translation progress|

Replaced by the translation progress of the document. This substitution is intended for use by document translators as a marker for the translation progress of the document.