パラグラフ階層のマークアップ

これらのディレクティブは短いパラグラフ(段落)を作成します。通常のテキスト同様、情報の固まりに対して使用できます。

.. note::

特別に重要な情報が少しだけある場合に使用します。APIを使用する際に、ユーザが気をつけなければならないことの説明をする場合などに使うと良いでしょう。このディレクティブの中身には、適切に句読点が付いた、完全な文章を書くべきです。

サンプル:

.. note::

   This function is not suitable for sending spam e-mails.
.. warning::

noteよりも重要な情報があり、APIを使用する際に、気をつけなければならない警告情報をユーザに伝えるために使用するのに適しています。このディレクティブの中身には、適切に句読点が付いた、完全な文章を書くべきです。 note との違いで言えば、セキュリティに関する情報は note よりもこのディレクティブを使用する方が良いでしょう。

.. versionadded:: version

このディレクティブは説明している機能がライブラリ、もしくはC APIに追加された時のプロジェクトのバージョンについて記述するのに使用します。このディレクティブがモジュール全体に対して適用する場合には、モジュールセクションの先頭の、文章が始まる前の位置に置くべきです。

最初の引数は必須で、バージョン番号を書く必要があります。2番目の引数も追加でき、変化に対する 短い 説明を書くことができます。

サンプル:

.. versionadded:: 2.5
   The *spam* parameter.

ディレクティブヘッドと説明の間には空行を入れてはいけません。マークアップの中では見た目上つながっているようにしなければなりません。

.. versionchanged:: version

versionadded と似ていますが、現在説明している機能がいつどのように変化したのか(新しい引数、副作用の変更など)を説明するのに使用します。

.. deprecated:: version

versionchanged と似ていますが、このディレクティブは、この機能がすでに古くて非推奨になったことを示しています。代替として、今後何を使っていくべきなのかといった説明文を付けることができます:

.. deprecated:: 3.1
   Use :func:`spam` instead.

.. seealso::

多くのセクションがモジュールのドキュメントへの参照やが、外部ドキュメントへの参照を含む場合、このようなリストは seealso ディレクティブを使用して作ることができます。

seealso ディレクティブはサブセクションの直前のセクションに置かれることが多いです。HTMLアウトプットにおいては、メインのテキストの流れから離されて、箱に囲まれて表示されます。

seealso の中身は、reSTの定義リストを使用しなければなりません。 サンプル:

.. seealso::

   Module :py:mod:`zipfile`
      Documentation of the :py:mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

“短縮形”の書き方もサポートされており、以下のように書くことができます:

.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

バージョン 0.5 で追加: “短縮形”を追加。

.. rubric:: title

このディレクティブは、目次に表示されないパラグラフの見出しを作成します。(訳注:rubricは注釈の意味です)

注釈

もし rubricディレクティブの タイトル が”Footnotes”(もしくは選択された言語で指定されている、同様の言葉)だった場合には、脚注の定義だけが含まれていると見なして、LaTeXライターでは無視されます。この場合は空の見出しだけが作成されます。

.. centered::

このディレクティブはセンターに置かれた、太字のテキストを作成するのに使用します。以下のように使用されます:

.. centered:: LICENSE AGREEMENT

バージョン 1.1 で撤廃: この表示専用のディレクティブは古いバージョンからの遺産です。代わりに rst-class ディレクティブを使い、適切なスタイルを追加してください。

.. hlist::

このディレクティブは短い文章のリストを含みます。このディレクティブは、水平にも数カラム展開することで、よりコンパクトなリストに変換するか、アイテム間のスペースを小さくします。どちらになるかはビルダー次第です。

水平に展開する機能をサポートしたビルダーでは、 columns オプションを使用して、水平のカラム数の設定できます。デフォルトでは2になっています。サンプルを示します:

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

バージョン 0.6 で追加.

目次のマークアップ

サブドキュメントの目次を作る toctree ディレクティブに関しては TOCツリー のドキュメントを読んでください。

ローカルな目次を作成する場合には、標準 reSTの contents ディレクティブ を使用してください。

用語集

.. glossary::

このディレクティブは、用語と定義が一緒になった、マークアップのようなreST定義リストを含みます。定義は term というロールを利用することで参照が可能になります。 サンプル:

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

通常の定義リストとは異なり、一つのエントリーに対して、複数の 用語を定義できます。それぞれの用語に対してインラインマークアップを使えます。また、すべての用語への参照も可能です:

.. glossary::

   term 1
   term 2
      Definition of both terms.

(用語集がソートされる場合、最初の項がソート順序を決定します。)

If you want to specify “grouping key” for general index entries, you can put a “key” as “term : key”. For example:

.. glossary::

   term 1 : A
   term 2 : B
      Definition of both terms.

Note that “key” is used for grouping key as is. The “key” isn’t normalized; key “A” and “a” become different groups. The whole characters in “key” is used instead of a first character; it is used for “Combining Character Sequence” and “Surrogate Pairs” grouping key.

In i18n situation, you can specify “localized term : key” even if original text only have “term” part. In this case, translated “localized term” will be categorized in “key” group.

バージョン 0.6 で追加: glossary ディレクティブに :sorted: フラグを追加することで、アルファベット順に自動的にソートされるようになりました。

バージョン 1.1 で変更: 複数の用語をサポートし、また、用語の中でインラインマークアップを使えるようになりました。

バージョン 1.4 で変更: Index key for glossary term should be considered experimental.

文法規則表示

形式がきちんとした文法の規則を表示するための特別なマークアップを利用できます。マークアップはシンプルに作られています。その代わりに、BNFや、BNFの派生の記法をすべてのモデル化することは目標とされていませんが、文脈自由文法を表現するには十分な機能を持っていて、シンボルを書くと、定義にリンクが張られるようにレンダリングされます。以下のディレクティブがあります:

.. productionlist:: [name]

このディレクティブは文法の規則を表現するためのものです。それぞれの規則は一行で表現され、コロン(:)の前が名前で、その後ろが定義になります。定義を複数行で書くこともできますが、この場合は、それぞれの定義の行の先頭に、最初の行と同じ高さにそろえてコロンを書く必要があります。

productionlist に与える名前によって、異なる文法に属する、異なる規則セットのグループと区別できるようになります。

ディレクティブの引数の 規則リスト の中には空行を入れることはできません。

定義には解釈済みのテキストとしてマークされたトークン名を含むことができます。これらのトークンの規則との間にクロスリファレンスが生成されます。(例 sum ::= `integer` "+" `integer`) 文法規則のリストその外では、 token ロールを使って、文法への参照を取ることができます。

規則の中ではreSTパーサは動作しないため、 * や、 | といった文字をエスケープすることはできません。

次のサンプルは、Pythonのリファレンスマニュアルにあった構文をSphinxで表現したものです:

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