.. highlightlang:: rest

拡張マークアップ構成部 (Additional Markup Constructs)
======================================================

Sphinx は標準の reST マークアップに対して、たくさんのディレクティブと
"interpreted text roles" を拡張しています。
このセクションにはそれらの拡張された構成部のリファレンスがあります。
"標準"の reST 構成部は、 Python ドキュメントで使用されてはいますが、
そのドキュメントはここにはありません。

.. note::

   これは Sphinx の拡張マークアップの機能の概要です。
   網羅された情報は `Sphinxのドキュメント
   <http://sphinx.pocoo.org/contents.html>`_ にあります。

メタ情報マークアップ (Meta-information markup)
------------------------------------------------

.. describe:: sectionauthor

   現在のセクションの著者を示します。引数には、(公表されないにしても)公表されても
   良いような名前と、email アドレスを含むべきです。
   アドレスのドメイン名部分は小文字で記述されるべきです。例::

      .. sectionauthor:: Guido van Rossum <guido@python.org>

   現在のところ、このマークアップは出力には全く利用されていませんが、だれが貢献した
   のかを把握するのに役に立っています。


モジュール用のマークアップ (Module-specific markup)
----------------------------------------------------

この節では、ドキュメント中のモジュールに関する情報を提供するために使われるマークアップに
ついて説明します。各モジュールは各々のファイルでドキュメントされるべきです。
通常このマークアップは、そのファイルのタイトルヘッダの後に使います。典型的な
ファイルは次のように始まります::

   :mod:`parrot` -- Dead parrot access
   ===================================

   .. module:: parrot
      :platform: Unix, Windows
      :synopsis: Analyze and reanimate dead parrots.
   .. moduleauthor:: Eric Cleese <eric@python.invalid>
   .. moduleauthor:: John Idle <john@python.invalid>

ごらんの通り、モジュール専用マークアップは、 ``module`` と ``moduleauthor``
という二つのディレクティブから成ります。

.. describe:: module

   このディレクティブはモジュールの説明の始まりを示します。
   （パッケージのサブモジュールの場合は、モジュール名はパッケージ名を含めて全体を
   記述すること）

   ``platform`` オプションは、そのモジュールが利用可能なプラットフォームをカンマで
   区切ったリストです。（全てのプラットフォームで利用可能であるなら、このオプションは
   外すべきです）要素は短い識別子で、 "IRIX", "Mac", "Windows", "Unix" などが使われ
   ています。できるだけ、すでに使われている識別子を使うようにしてください。

   ``synopsis`` オプションは、モジュールの目的を説明する一文で構成されます。
   これは、現在のところ、 Global Module Index でのみ利用されています。

.. describe:: moduleauthor

   ``moduleauthor`` ディレクティブは、 ``sectionauthor`` と同じで、作者の名前になります。
   このディレクティブは、作者の人数だけ繰り返して利用できます。
   現在、このディレクティブは出力に利用されていません。


.. note::

   モジュールを解説するファイルのセクションタイトルは、概要ファイルの中の
   table-of-contents ツリーに利用されるので、意味が解るようにしてください。


情報単位 (Information units)
----------------------------

モジュールが提供する機能を解説するために使うディレクティブが幾つかあります。
各ディレクティブは、何を説明しようとしているのかを判別する情報として
一つかそれ以上のシグネチャを必要とします。そして、ディレクティブの内容は
その解説であるべきです。
デフォルトではディレクティブはインデックスのエントリに登録されます。
インデックスのエントリが必要ない場合は、ディレクティブオプションとして
``:noindex:`` というフラグを追加します。
次の例は、ここまでで説明した要素を全て含んだディレクティブになります::

    .. function:: spam(eggs)
                  ham(eggs)
       :noindex:

       Spam or ham the foo.

オブジェクトのメソッドやデータ属性(attribute)のシグネチャは、文脈からどの型に
属しているかが明らかな場合であっても、 (``.. method::FileInput.input(...)``) の
ように型名を含める必要があります。これは、一貫したクロスリファレンスを実現する
ためです。
"context managers" といった抽象プロトコルに属するメソッドを解説する場合にも、
インデックスを判りやすくするために、（仮想）型名を付けてください。

ディレクティブは以下の通りです。

.. describe:: c:function

   Cの関数を説明します。シグネチャはC言語のまま付けてください。例::

      .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

   このディレクティブは関数ライクなプリプロセッサマクロを説明するのにも使います。
   引数の名前を省略しないでください。引数の名前を説明の中で利用できます。

   シグネチャの中のアスタリスクをバックスラッシュでエスケープしなくても良いことを
   覚えておいてください。reST のインラインに対するパース処理は行われません。

.. describe:: c:member

   Cの構造体メンバを説明します。シグネチャの例::

      .. cmember:: PyObject* PyTypeObject.tp_bases

   説明文は、値の取り得る範囲、値がどのように扱われるか、値を変更しても良いのかどうかに
   ついて記述するべきです。テキストの中で構造体のメンバを参照するときには ``member`` role を
   利用するべきです。

.. describe:: c:macro

   "シンプル"な C言語のマクロについて説明します。シンプルなマクロとは、引数を取らず、
   関数として解説されないものです。このディレクティブは単純な定数の定義には利用しません。
   Python ドキュメントの中でこのディレクティブが使われている例には、 :c:macro:`PyObject_HEAD` と
   :c:macro:`Py_BEGIN_ALLOW_THREADS` があります。

.. describe:: c:type

   C の型を説明します。シグネチャは単に型の名前であるべきです。

.. describe:: c:var

   C のグローバル変数を説明します。シグネチャは、次の例のように、型を含めるべき
   です::

      .. cvar:: PyObject* PyClass_Type

.. describe:: data

   モジュール内のグローバルなデータを説明します。変数にも、 "定数として宣言された"
   値にも利用します。クラスとオブジェクトの属性にはこのディレクティブを使いません。

.. describe:: exception

   例外クラスについて説明します。シグネチャは、必要ではありませんが、コンストラクタ
   引数と丸括弧を含むことができます。

.. describe:: function

   モジュールレベル関数を説明します。シグネチャには引数を記述するべきです。
   オプションの引数は角括弧で囲みます。明快さのために必要であれば、デフォルト値を
   含めることもできます。例::

      .. function:: repeat([repeat=3[, number=1000000]])

   このディレクティブはオブジェクトメソッドには利用されません。モジュールの名前空間にあり、
   モジュールの公開インタフェースになっている、束縛済みのオブジェクトメソッド
   (Bound object method) については、通常の関数とほとんど変わらないので、
   このディレクティブを使います。

   説明文は、必要とされる引数と、それがどのように使われるか（特に、可変(mutable) オブジェクトが
   変更されるかどうか）、副作用、発生しうる例外についての情報を含むべきです。
   小さな例を提供するのも良いでしょう。

.. describe:: class

   クラスを説明します。シグネチャには丸括弧とコンストラクタ引数を含めることが
   できます。

.. describe:: attribute

   オブジェクトの属性を説明します。説明文は、期待されるデータ型と、直接変更しても
   良いかどうかを含むべきです。このディレクティブは、下記の例のように、
   クラスディレクティブの中にネストするべきです::
   
      .. class:: Spam

            クラスの解説

            .. attribute:: ham

               属性の解説

   .. 原文では attribute:: ではなく data:: になっていたが間違いだろう
   
   例えば、異なる属性やメソッドを複数のドキュメントに分けるときなどに、
   属性のドキュメントは、クラスディレクティブの外に置くことも出来ます。
   このとき、明示的にクラス名を含むべきです::

      .. attribute:: Spam.eggs
  
.. describe:: method

   オブジェクトメソッドを説明します。パラメータからは、 ``self`` パラメータを除外
   するべきです。説明文は ``function`` と同じような情報を提供するべきです。
   このディレクティブは、上記の例のように、
   クラスディレクティブの中にネストするべきです

.. describe:: opcode

   Python バイトコード(:term:`bytecode`)の命令を説明します。

.. describe:: cmdoption

   Python のコマンドラインオプションもしくはスイッチを説明します。
   オプションの引数名は <> の括弧で囲います。 例::
 
       .. cmdoption:: -m <module>
 
          module をスクリプトとして実行します。

.. describe:: envvar

   Python が利用したり定義している環境変数を説明します。

もっと汎用的なバージョンの以下のディレクティブもあります:

.. describe:: describe

   このディレクティブは、上で説明したディレクティブと同じフォーマットを生成しますが、
   インデックスエントリやクロスリファレンスターゲットは生成しません。
   このディレクティブは、たとえば、このドキュメントでディレクティブの説明をする
   ために利用しています。例::

      .. describe:: opcode

         Python バイトコードの命令を説明します。


コードサンプルを表示する (Showing code examples)
--------------------------------------------------

Python ソースコードやインタラクティブセッションの例は、 reST 標準のリテラルブロックを
利用して書きます。手前の段落の最後を ``::`` にして、インデントで範囲を指定します。

インタラクティブセッションを表現するときは、プロンプトと出力を Python コードと一緒に
書いてください。インタラクティブセッションに対して特別なマークアップは用意されて
いません。入力か出力の最後の行の後に、 "使用されない" プロンプトを入れてはいけません。
次の例のように *してはいけません* ::

   >>> 1 + 1
   2
   >>>

シンタックスハイライトはスマートに処理されます:

* 各ソースファイルには、 "ハイライト言語" があります。多数のファイルで Python の
  コードをハイライトするために、デフォルトでは ``'python'`` に設定されています。

* Python ハイライティングモードでは、インタラクティブセッションは自動的に認識
  されて適切にハイライトされます。

* ハイライト言語は ``highlightlang`` ディレクティブを利用して変更することができます。
  以下のようにして利用します::

     .. highlightlang:: c

  このディレクティブで設定されたハイライト言語は、次の ``highlightlang`` ディレクティブ
  まで有効になります。　

* ハイライト言語のよく使われる値は以下の通りです:

  * ``python`` (デフォルト)
  * ``c``
  * ``rest``
  * ``none`` (ハイライトなし)

* 現在のハイライト言語でのハイライティングに失敗した場合、そのブロックは全く
  ハイライトされません。

長い、そのまま表示されるテキストは、外部のプレインテキストのみで書かれたファイルに
格納して、取り込む (include) こともできます。その場合、標準の ``include`` ディレクティブに
``literal`` オプションフラグを付けて利用します。たとえば、 :file:`example.py` という
Python ソースファイルを取り込む場合は::

   .. include:: example.py
      :literal:


インラインマークアップ (Inline markup)
--------------------------------------

前に述べたように、 Sphinx はドキュメント内に意味に基づくマークアップを挿入する
ために、 "interpreted text roles" を使います。

関数/メソッドの引数のようなローカル変数名は例外で、シンプルに ``*var*``
とマークされます。

その他の全ての role について、 ``:rolename:`content``` のように書く必要があります。

そのほかにもクロスリファレンス role をより他用途にする便利な機能があります。

* 明示的なタイトルと参照ターゲットを、 reST の直接ハイパーリンクのように書くことができます:
  ``:role:`title <target>``` は *target* を参照しますが、リンクテキストは *title*
  になります。

* コンテントにprefix ``!`` を付けると、参照もハイパーリンクも作られません。

* Python オブジェクトのロールにおいて、コンテントに ``~`` というprefixをつけると、
  リンクターゲットはターゲットの最後の部分になります。例えば、 ``:meth:`~Queue.Queue.get```
  は ``Queue.Queue.get`` を参照しますが、リンクテキストとしては ``get``
  だけを表示します。

  HTML出力において、そのリンクの ``title`` 属性 (例えばマウスオーバー時のツールチップに
  表示される) は完全なターゲット名になります。

以下の roles はモジュール内のオブジェクトを参照し、該当する識別子があればハイパーリンクを
作成します。

.. describe:: mod

   モジュールの名前。ドット付きの名前も使われる。これはパッケージの名前にも使う。

.. describe:: func

   Python 関数の名前。ドット付きの名前も使われる。可読性のために、 role のテキストには
   後ろの丸括弧も含めるべきである。丸括弧は該当する識別子を検索するときには無視される。

.. describe:: data

   モジュールレベル変数や定数の名前。

.. describe:: const

   定数として "宣言された" 名前。これは C言語の ``#define`` か、
   Python の変更されないことを意図された変数である。

.. describe:: class

   クラス名。ドット付きの名前も使われる。

.. describe:: meth

   オブジェクトメソッドの名前。 role テキストには型の名前と、メソッド名、後続の
   丸括弧を含めるべきである。ドット付きの名前も使われる。

.. describe:: attr

   オブジェクトのデータ属性の名前。

.. describe:: exc

   例外の名前。ドット付きの名前も使われる。

このマークアップで囲まれた名前は、モジュール名とクラス名の両方あるいは片方を
含めることができます。たとえば、 ``:func:`filter``` は、現在のモジュール内にある
``filter`` という名前の関数か、その名前のビルトイン関数を参照できます。
それに対して、 ``:func:`foo.filter``` とすると、はっきりと ``foo`` モジュールの
中の ``filter`` 関数だけを参照します。

同じようなことが、ある名前が現在ドキュメントしているクラスの属性かどうかを
決定する際にも行われます。

以下の roles は、その C言語の要素が API ドキュメントにあれば、それに対する
クロスリファレンスを作成します。

.. describe:: cdata

   C言語の変数の名前。

.. describe:: cfunc

   C言語の関数の名前。後続の丸括弧も含めるべきである。

.. describe:: cmacro

   前述した、 "シンプルな" C のマクロの名前。

.. describe:: ctype

   C言語の型の名前。


以下の role はクロスリファレンスは作るかもしれませんが、オブジェクトを参照する
事はありません。

.. describe:: token

   文法上のトークンの名前。(リファレンスマニュアルにおいて、出力間のリンクを
   作成するために使われます)

---------

以下の roles はテキストのフォーマットスタイルを変更する以外何もしません。

.. describe:: command

   ``rm`` のような、OS レベルのコマンドの名前。

.. describe:: dfn

   テキストの中で定義される語をマークする。 (インデックスエントリは
   作成されない)

.. describe:: envvar

   環境変数。インデックスエントリが作成される。

.. describe:: file

   ファイルやディレクトリの名前。この中では、 "可変" な部分を示すために
   波括弧 "{}" を利用できる。例::

      ... は :file:`/usr/lib/python2.{x}/site-packages` にインストールされます ...

   ビルドされたドキュメントの中では、この ``x`` は、 Python マイナーバージョンで
   置き換えられることを示すために、違った形式で表示されます。

.. describe:: guilabel

   インタラクティブなユーザーインタフェースの一部として表示されているラベルは、
   ``guilabel`` を使ってマークされるべきです。これには、 :mod:`curses` やその他の
   テキストベースのライブラリを利用して作られた、テキストベースのインタフェースの
   中のラベルも含みます。ボタンラベル、ウィンドウタイトル、フィールド名、メニューと
   その項目、選択リスト内の要素など、インタフェース内のどんなラベルにも、この role を
   利用するべきです。

.. describe:: kbd

   キーストロークシーケンスをマークアップします。キーシーケンスをどんな形式で表現
   するかは、プラットフォームやアプリケーションごとに慣習があります。適切な慣習が
   無い場合は、初心者や非ネイティブスピーカーにも判るように、修飾キー (modifier key)
   を省略形にしないでください。例えば、 *xemacs* キーシーケンスは、 ``:kbd:`C-x C-f```
   のように記述できますが、特定のアプリケーションやプラットフォームに関連づけられて
   いない場合は、このキーシーケンスは ``:kbd:`Control-x Control-f``` とマークアップ
   されるべきです。

.. describe:: keyword

   プログラミング言語の予約後(keyword).

.. describe:: mailheader

   RFC 822 形式のメールヘッダの名前。このマークアップは、そのヘッダが e-mail で
   利用されることを意味するわけではなく、同じ "スタイル" のどんなヘッダを参照する
   のにも使えます。多種の MIME 仕様で定義されているヘッダにも利用されます。ヘッダの
   名前は、実際に利用される場合と同じように書くべきで、一般的な使い方が複数ある
   場合は camel-case が好まれます。例: ``:mailheader:`Content-Type```.

.. describe:: makevar

   :command:`make` の変数名。

.. describe:: manpage

   セクションを含む、Unix manual page への参照。例: ``:manpage:`ls(1)```.

.. describe:: menuselection

   メニュー項目は ``menuselection`` role を使ってマークアップされるべきです。
   これは、サブメニューや特定の操作のの選択を含め、完全なメニュー項目の並びや、
   その一部をマークアップするのに使われます。各項目の名前は ``-->`` を使って
   区切るべきです。

   例えば、"スタート > プログラム" をマークアップする場合は、次の様にします::

      :menuselection:`スタート --> プログラム`

   幾つかのOSで、メニュー項目の後ろに何か記号を付けてダイアログボックスを開く
   事を示すといったことがあります。そういったメニュー項目の後ろに続く表記は、
   メニュー項目名に含めないべきです。

.. describe:: mimetype

   MIME type もしくは MIME type の構成要素 (メジャーもしくはマイナー部分だけ)
   の名前。

.. describe:: newsgroup

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

.. describe:: option

   実行可能プログラムのコマンドラインオプション。先頭のハイフンも含めなければ
   ならない。

.. describe:: program

   実行可能プログラムの名前。幾つかのプラットフォームでは、実行可能ファイル名と
   異なるかもしれない。特に、Windows のプログラムでは、 ``.exe`` (もしくは他の)
   拡張子は除くべきである。

.. describe:: regexp

   正規表現。クォートを含めるべきではない。

.. describe:: samp

   コードのようなリテラルテキスト。
   ``:file:`` と同じく、この中では "可変" な部分を示すために波括弧を
   利用できます。

   "可変" 部分が要らないのであれば、通常の ````code```` を使ってください。


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

.. describe:: pep

   Python Enhancement Proposal への参照。これは適切なインデックスのエントリを
   生成する。HTML出力では、 "PEP *number*\ " というテキストが生成され、この
   テキストは指定された PEP のオンラインコピーへのハイパーリンクになる。

.. describe:: rfc

   Internet Request for Comments (RFC) への参照。これは適切なインデックスのエントリを
   生成する。HTML 出力では "RFC *number*\ " というテキストが生成され、この
   テキストは指定された RFC のオンラインコピーへのハイパーリンクになる。


ハイパーリンクのために特別な role が用意されていないことに注意してください。
reST 標準の方法がその目的に利用できるからです。


.. _doc-ref-role:

クロスリンクのマークアップ (Cross-linking markup)
-------------------------------------------------

ドキュメント中の任意のセクションに対してのクロスリファレンスをサポートするには、
reST 標準のラベルはあまり良くありません。全てのラベルはセクションタイトルの前に
おかなければならず、全てのラベルの名前はドキュメントのソース全体に渡って
ユニークでなければなりません。

そこで、セクションを参照するのには ``:ref:`label-name``` という role を、利用
できます。


例::

   .. _my-reference-label:

   クロスリファレンスされるセクション
   ----------------------------------

   セクションの文字列。

   このセクション自体を参照します。 :ref:`my-reference-label` を見てください。

   .. _my-reference-label:

``:ref:`` の部分はセクションタイトルで置き換えられます。


段落レベルでのマークアップ (Paragraph-level markup)
---------------------------------------------------

以下のディレクティブは、通常のテキストと同じように情報単位の中で利用でき、
短いパラグラフを作成します。

.. describe:: note

   この note に関係あるどの API を利用するときにも、ユーザーが気をつけるべき
   特に重要な情報。このディレクティブの内容は完全な文で、適切な句読点を全て含め
   なければなりません。

   例::

      .. note::

         この関数はスパムメールを送るためのものではありません。

.. describe:: warning

   この warning に関係あるどの API を使うときにでも、ユーザーがとても慎重になるべき
   重要な情報。このディレクティブの内容は完全な文で、適切な句読点を全て含め
   なければなりません。
   警告だらけのページでユーザーを怖がらせないように、 ``node`` ではなく
   warning を使うのは、クラッシュ、データ損失、セキュリティに関する情報だけに
   留めるべきです。

.. describe:: versionadded

   このディレクティブは、どのバージョンの Python で対象の要素がライブラリや C API
   に追加されたのかを示します。このディレクティブがモジュール全体に適用する場合、
   ディレクティブをモジュールセクションのどの文章よりも先におかれるべきです。

   最初の引数は必須で、バージョンです。二つ目の引数は任意で、変更点の *簡潔な*
   説明です。

   例::

      .. versionadded:: 2.5
         *spam* 引数.

   ディレクティブの先頭行と説明との間に空行を入れてはならないことに注意してください。
   これはマークアップされたときにブロックが視覚的に連続するためです。

.. describe:: versionchanged

   ``versionadded`` とほとんど同じですが、対象の要素がいつどのように変更 (新しい引数が
   追加された、副作用が変わった、等) されたかを説明します。

--------------

.. describe:: impl-detail

   このディレクティブは、 CPython に限定された情報を区別するために使います。
   ブロック要素としても、一文の引数としても利用できます。例えば ::

      .. impl-detail::

         This describes some implementation detail.

         More explanation.

   または、 ::

      .. impl-detail:: This shortly mentions an implementation detail.

   内容の先頭に、自動的に "\ **CPython implementation detail:**\ "
   という一文が入ります。

.. describe:: seealso

   たくさんのセクションで、モジュールドキュメントや外部ドキュメントが参照されています。
   これらのリストは、 ``seealso`` ディレクティブで作成されます。

   ``seealso`` ディレクティブは一般的に、セクションの中で、どのサブセクションより
   前に置かれます。 HTML 出力では、本文の流れから切り離された区画の中に表示されます。

   ``seealso`` ディレクティブの中身は、 reST の定義リストであるべきです。例::

      .. seealso::

         Module :mod:`zipfile`
            :mod:`zipfile` 標準モジュールのドキュメント。

         `GNU tar manual, Basic Tar Format <http://link>`_
            GNU tar 拡張を含む、 tar アーカイブファイルのドキュメント。

.. describe:: rubric

   このディレクティブは、目次 (table of contents) の項目にならない段落見出しを
   作ります。現在のところ、 "脚注" キャプションに利用されています。

.. describe:: centered

   このディレクティブは、センタリングされた太字の段落を作ります。次のようにして
   使います::

      .. centered::

         段落の内容

Table-of-contents マークアップ (Table-of-contents markup)
---------------------------------------------------------

reST が複数のドキュメントを繋いだり、ドキュメントを複数のファイルに分割して出力する
機能を持たないので、 Sphinx は table-of-contents を作成したり、ドキュメントの元ファイル
間に関連を持たせたりするためにカスタムのディレクティブを利用しています。 ``toctree``
ディレクティブはその中心になる要素です。

.. describe:: toctree

   このディレクティブは、ディレクティブの要素として与えられたファイルの中の TOCs
   ("sub-TOC trees" を含む) から作成した "TOC tree" をその場所に挿入します。
   ``maxdepth`` オプションに数値を指定することで、 "TOC tree" の深さを指定できます。
   デフォルトでは全レベルを利用します。

   次の例(ライブラリリファレンスインデックスから持ってきました)を考えてみます::

      .. toctree::
         :maxdepth: 2

         intro
         strings
         datatypes
         numeric
         (もっとたくさん)

   このディレクティブは二つの事を行います:

   * 指定されたファイル全てから TOC を作ります。深さが２、つまり一段階ネストした
     見出しまで含まれます。各ファイルの中の ``toctree`` ディレクティブも含まれます。

   * Sphinx は ``intro``, ``strings``, ... というファイルの相対順序と、それぞれの
     ファイルが現在のライブラリインデックスというファイルの子供である事を識別します。
     この情報から、 "next chapter", "previous chapter", "parent chapter" というリンクが
     作成されます。

.. TODO: 日本語ドキュメントをビルドしたときにリンクがどういう文字列になるか確認する。

   最後に、ビルドされる全てのファイルはどこか一つの ``toctree`` ディレクティブに
   出現しなければなりません。どこにも含まれていないファイルがあると、そのファイルは
   標準のナビゲーションで到達不可能になるので、 Sphinx は警告を出します。

   特別な ``contents.rst`` というソースディレクトリのルートにあるファイルは、
   TOC tree 階層の "root" になります。このファイルから "コンテンツ" ページが
   作成されます。

.. TODO: 各用語を、カタカナにするべきか、アルファベットのままにするべきかを、
   Sphinx のビルド結果を元にチェックする。

インデックス生成マークアップ (Index-generating markup)
------------------------------------------------------

Sphinx は自動的にインデックスのエントリを、先に述べた全ての情報の単位
(function, class, attribute のような) から作成します。

しかし、インデックスをより有用なものにしたり、言語リファレンスのような情報が
情報の単位の中に含まれないようなドキュメントでもインデックスのエントリを作成
できるようにするために、明示的なディレクティブも利用可能です。

そのディレクティブは ``index`` で、一つかそれ以上のインデックスエントリを含みます。
各エントリは、種類と値をコロンで区切ったもので構成されます。

例::

   .. index::
      single: execution!context
      module: __main__
      module: sys
      triple: module; search; path

このディレクティブは５つのエントリを持ち、 index 文の場所へのリンクになっている
インデックスエントリに変換されます。(もしくは、オフラインメディアの場合、該当する
ページ番号になります)

利用可能なエントリの種類は:

single
   単独のインデックスエントリを生成します。サブエントリのテキストをセミコロンで
   区切る（これは以降の種類でも、どんなエントリを作るのかを指定するときに使います）
   ことによってサブエントリを作成できます。
pair
   ``pair: loop; statement`` は、 ``loop; statement`` と ``statement; loop`` という
   名前の二つのインデックスエントリを一度に作成するショートカットです。
triple
   同じように、 ``triple: module; search; path;`` は、 ``module; search path``,
   ``search; path, module``, ``path; module search`` というエントリを作成する
   ショートカットです。
module, keyword, operator, object, exception, statement, builtin
   これらは全て二つのインデックスエントリを作成します。例えば、 ``module: hashlib`` は、
   ``module; hashlib`` と ``hashlib; module`` を作ります。

文法導出表記 (Grammar production displays)
------------------------------------------

形式的な文法の導出を表示するための特別なマークアップが利用可能です。
このマークアップはシンプルで BNF (やその派生系) の全ての側面を表そうとはしていま
せんが、文脈自由文法 (context-free grammer) を、記号が使われている部分からその
記号の定義部分へハイパーリンクが張られている形で表記するために十分な能力を
提供しています。

.. describe:: productionlist

   このディレクティブは導出のグループを囲むために使われます。各導出は一つの行として
   渡され、名前と、コロンで区切られた残りの定義で構成されます。定義が複数行に
   渡る場合は、継続する各行は最初の行のコロンと同じ位置にあるコロンで始まらなければ
   なりません。

   空行は ``productionlist`` ディレクティブの引数として許可されていません。

   定義には interpreted text としてマークアップされたトークン名を使うことができます。
   (例: ``unaryneg ::= "-" `integer```) -- これは、各トークンの導出に対する
   クロスリファレンスを作成します。代替を示すために利用される縦棒はバックスラッシュで
   エスケープしなければならないことに気をつけてください。そうしないと、 reST パーサーは
   縦棒を置換参照 (substitution reference) として認識するからです。

   production においては、これ以上の reST パース処理が行われない事に注意してください。
   なので、 ``*`` や ``|`` といった文字をエスケープする必要がありません。


.. XXX describe optional first parameter

以下は Python リファレンスマニュアルの中の例です::

   .. productionlist::
      try_stmt: try1_stmt \| try2_stmt
      try1_stmt: "try" ":" :token:`suite`
               : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+
               : ["else" ":" :token:`suite`]
               : ["finally" ":" :token:`suite`]
      try2_stmt: "try" ":" :token:`suite`
               : "finally" ":" :token:`suite`


置換 (Substitutions)
--------------------

ドキュメントシステムはデフォルトで定義されている３種類の置換を用意しています。
それらはビルド設定ファイル :file:`conf.py` で設定されます。

.. describe:: |release|

   ドキュメントが言及している Python のリリースへ置換されます。これは、例えば
   ``2.5.2b3`` のような、 alpha/beta/release candiate
   を含む完全バージョン文字列です。

.. describe:: |version|

   ドキュメントが言及している Python バージョンへ置換されます。これは、たとえば
   バージョン 2.5.1 において ``2.5`` の様に、バージョン文字列のうちメジャー・
   マイナー部のみで構成されます。

.. describe:: |today|

   今日の日付か、ビルド設定ファイルで指定された日付のどちらかに置換されます。
   通常は ``April 14, 2007`` のようなフォーマットになります。

