これらのディレクティブは短いパラグラフ(段落)を作成します。通常のテキスト同様、情報の固まりに対して使用できます。
特別に重要な情報が少しだけある場合に使用します。APIを使用する際に、ユーザが気をつけなければならないことの説明をする場合などに使うと良いでしょう。このディレクティブの中身には、適切に句読点が付いた、完全な文章を書くべきです。
サンプル:
.. note:: この関数はspamの電子メールを送付するには適しません。
このディレクティブは説明している機能がライブラリ、もしくはC APIに追加された時のプロジェクトのバージョンについて記述するのに使用します。このディレクティブがモジュール全体に対して適用する場合には、モジュールセクションの先頭の、文章が始まる前の位置に置くべきです。
最初の引数は必須で、バージョン番号を書く必要があります。2番目の引数も追加することができ、変化に対する 短い 説明を書くことができます。
多くのセクションがモジュールのドキュメントへの参照やが、外部ドキュメントへの参照を含む場合、このようなリストは seealso ディレクティブを使用して作ることができます。
seealso ディレクティブはサブセクションの直前のセクションに置かれることが多いです。HTMLアウトプットにおいては、メインのテキストの流れから離されて、箱に囲まれて表示されます。
seealso の中身は、reSTの定義リストを使用しなければなりません。
サンプル:
.. seealso::
Module :mod:`zipfile`
標準モジュールの :mod:`zipfile` のドキュメント。
`GNU tar マニュアル, 基本Tarフォーマット <http://link>`_
GNUによるtar拡張も含む、tarアーカイブファイルのドキュメント。
“短縮形”の書き方もサポートされており、以下のように書くことができます:
.. seealso:: modules :mod:`zipfile`, :mod:`tarfile`
バージョン 0.5 で追加: 短縮形の追加
このディレクティブは、目次に表示されないパラグラフの見出しを作成します。(訳注:rubricは注釈の意味です)
ノート
もし rubricディレクティブの タイトル が”Footnotes”だった場合には、脚注の定義だけが含まれていると見なして、LaTeXライターでは無視されます。この場合は空の見出しだけが作成されます。
このディレクティブはセンターに置かれた、太字のテキストを作成するのに使用します。以下のように使用されます:
.. centered:: ラインセンス契約
このディレクティブは短い文章のリストを含みます。このディレクティブは、水平にも数カラム展開することで、よりコンパクトなリストに変換するか、アイテム間のスペースを小さくします。どちらになるかはビルダー次第です。
水平に展開する機能をサポートしたビルダーでは、 columns オプションを使用して、水平のカラム数の設定をすることができます。デフォルトでは2になっています。サンプルを示します:
.. hlist::
:columns: 3
* このリストの
* 短い項目は
* 表示するときに
* 水平に
* 表示されるべきです。
バージョン 0.6 で追加.
サブドキュメントの目次を作る toctree ディレクティブに関しては “Sphinxコンセプト”のドキュメントを読んでください。
ローカルな目次を作成する場合には、標準reSTの contents ディレクティブを使用してください。
Sphinxはすべての情報のユニット(関数、クラス、属性)から、自動的にインデックスのエントリーを作成します。
しかし、これ以外に明示的に指定するディレクティブもあります。これを使用することで、言語のリファレンスのように、メインの情報のユニットが存在しない情報をドキュメントの中に書いてインデックスのエントリーを作ることができるようになります。より包括的なインデックスを作成することができるようになります。
このディレクティブは一つ以上のインデックスのエントリーを含みます。それぞれのエントリーはコロン(:)で区切られた、タイプ、値を含みます。
サンプル:
.. index::
single: execution; context
module: __main__
module: sys
triple: module; search; path
実行時のコンテキスト
---------------------
...
このディレクティブは5つのエントリーを含んでいます。これらは生成されたインデックスのエントリーに変換され、index文の正確な位置へのリンクが張られることになります。オフラインのメディアに出力される場合には、リンクの代わりに対応するページ番号が出力されます。
indexディレクティブはそのソースの位置のターゲットとのクロスリファレンスを生成するため、それらが参照するものの 前の位置 に置くことが大切になります。上記のサンプルコードの例では、リンクを張りたい見出しの前に配置されています。
設定可能なエントリーのタイプは以下の通りです:
“single”のエントリーだけが含まれるindexディレクティブの場合、以下のように短縮記法で簡単に作成することもできます:
.. index:: BNF, grammar, syntax, notation
これは4つのインデックスのエントリーが作成されます。
用語集
このディレクティブは用語と定義がリストになった、reST定義リストを含みます。定義は term というロールを利用することで参照が可能になります。以下にサンプルを示します:
.. glossary::
環境
ルート以下のすべてのドキュメントの情報が格納される場所です。この情報はクロスリファレンスを作成する際に利用されます。この環境には、パース段階の後の結果のpickleされたものが入ります。ソースファイルが新規で作成されたり、変更されて、読み込んだりパースしたりする必要がない限りはこの中のデータが更新されることはありません。
ソースディレクトリ
ひとつのSphinxプロジェクトにおいて、すべてのソースファイルを含むディレクトリ。このディレクトリ直下だけではなく、サブディレクトリを使用してソースファイルを分類して入れておくことも可能です。
バージョン 0.6 で追加: glossaryディレクティブに :sorted: というフラッグを与えることができるようになりました。これを指定すると、自動的にエントリーをアルファベット順に並べることができます。
(訳注: grammar productionを文法規則と意訳してます)
形式がきちんとした文法の規則を表示するための特別なマークアップを利用することができます。マークアップはシンプルに作られています。その代わりに、BNFや、BNFの派生の記法をすべてのモデル化することは目標とされていませんが、文脈自由文法を表現するには十分な機能を持っていて、シンボルを書くと、定義にリンクが張られるようにレンダリングされます。以下のディレクティブがあります:
このディレクティブは文法の規則を表現するためのものです。それぞれの規則は一行で表現され、コロン(:)の前が名前で、その後ろが定義になります。定義を複数行で書くこともできますが、この場合は、それぞれの定義の行の先頭に、最初の行と同じ高さにそろえてコロン(:)を書く必要があります。
ディレクティブの引数の 規則リスト の中には空行を入れることはできません。
定義には解釈済みのテキストとしてマークされたトークン名を含むことができます。これらのトークンの規則との間にクロスリファレンスが生成されます。(例 sum ::= `integer` "+" `integer`)
規則の中ではreSTパーサは動作しないため、 * や、 | といった文字をエスケープすることはできません。
The following is an example taken from the Python Reference Manual:
.. 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`