この節は reStructuredText (reST) のコンセプトと文法の要約です。 ドキュメント作者の生産性のために十分な情報を提供することに注目しています。 reST はシンプルで、出しゃばらないマークアップ言語として設計されたので、 この文章はあまり長くありません。
参考
The authoritative reStructuredText User Documentation.
段落は reST においてもっとも基本的なブロックです。 一行以上の空行で区切られただけのテキストの固まりが段落になります。 Python と同じく、 reST ではインデントは重要な意味を持つので、同じ段落に属す 行は全て同じインデントレベルで左揃えする必要があります。
reST 標準のインラインマークアップは非常にシンプルです。
使ってください。
もしアスタリスクやバッククォートが通常のテキストの中で出てきて、インラインマーク アップ用の区切り文字と混合する場合は、バックスラッシュ(訳注: 日本語フォントでは、 一般的に円記号になります)でエスケープする必要があります。
インラインマークアップの幾つかの制限に気をつけてください:
これらの制限は将来のバージョンの docutils で解除されるかもしれません。
reST は独自の “interpreted text roles” に対応していて、囲まれたテキストを専用の 方法で解釈することができます。別の節で解説しますが、Sphinx はこれを、 意味に基づくマークアップと識別子のクロスリファレンスのために利用しています。 “interpreted text roles” の一般的な文法は :rolename:`内容` になります。
リストの表現は自然です: 段落の最初にアスタリスクをおいて、適切にインデント するだけです。番号付きリストも同じで、``#`` 記号を使えば自動的にナンバリング されます:
* これは番号なしリストです。
* リストの要素は二つあり、二つ目は
二行使用しています。
#. これば番号付きリストです。
#. こちらも要素が二つあります。
リストはネストさせることもできます。親になるリスト要素との間に空行が必要な ことに気をつけてください:
* これは
* リストで
* ネストされたリストと
* 子要素があります。
* そしてここは親のリストの続きです。
定義リストは次のようにして作ります:
単語 (行の終わりまで)
単語の定義。インデントされている必要がある。
複数の段落を持つことも可能。
次の単語
定義。
定義の部分は周りの段落よりも深くインデントします。
リテラルコードブロックは、特別なマーカー :: で終わる段落の次に始まります。 リテラルブロックはインデントしなければなりません。
これは通常の段落です。次の段落はコードサンプルです::
ここには、インデントの除去以外の
処理が行われません。
複数行にまたがることもできます。
ここでまた通常の段落になります。
:: マーカーの処理はスマートです:
なので、上の例での最初の段落の二つ目の文は、 “次の段落はコードサンプルです:” と 出力されます。
インラインでのWebリンクには、 `リンク文字列 <http://target>`_ を使ってください。 リンク文字列をアドレスにする場合は、マークアップしなくても、パーサーがリンクや メールアドレスを見つけて処理します。
内部リンクには、reSTの特別な role を利用します。特別なマークアップのセクションを 見てください。 doc-ref-role
セクションヘッダは、記号を使って、セクションタイトルにそれ以上の長さのアンダーライン (とオプションでオーバーライン) を引いて作ります。:
==============
ここにタイトル
==============
通常、特定の文字に特定の見出しレベルが割り当てられておらず、ヘッダ構造から 自動的にレベルが決まります。しかし、 Python ドキュメントにおいては、以下の ルールを使います:
reST において、 “明示的なマークアップ (explicit markup)” は、脚注、特別な ハイライト付きの文、コメント、一般的な指定のために利用されます。
明示的なマークアップのブロックは、 .. に空白が続いたものが行頭にあるときに 始まり、次の段落が同じインデントになるところで終わります。 (明示的なマークアップと 通常の段落の間には空行が必要です。すこし複雑に思えるかもしれませんが、ドキュメントを 書くときには十分に直感的です。)
ディレクティブは一般的な、明示的なマークアップを行うブロックです。 role のような reSTの拡張メカニズムの一つで、 Sphinx はディレクティブを多用しています。
基本的に、ディレクティブは、名前、引数、オプション、内容で構成されます。 (この XXX を覚えておいてください。次の章でカスタムディレクティブを説明するときに 出てきます。) 次の例を見てください
.. function:: foo(x)
foo(y, z)
:bar: no
ユーザーから入力されたテキスト一行を返す.
function はディレクティブの名前です。ここでは引数が二つあり、一つは一行目の 残りの部分で、もう一つは次の行です。オプションも一つ、 bar があります。 (ごらんの通り、オプションは引数の行のすぐ次の行にあり、コロンで示されます.)
一行の空行を挟んでディレクティブの内容が続きます。内容はディレクティブの開始位置と 同じ場所までインデントされます。
脚注を使うときは、 [#]_ を使って脚注を入れる場所を示し、脚注の内容はドキュメントの 最後に、次の例のように、”脚注” という rubic ヘッダの後に書きます。
Lorem ipsum [#]_ dolor sit amet ... [#]_
.. rubric:: 脚注
.. [#] 最初の脚注の内容
.. [#] 二つ目の脚注の内容
(上の脚注のような)有効なマークアップになっていない、全ての明示的な マークアップブロックは、コメントとして扱われます。
em dash や copyright sign のような特別な文字を reST に含める最も簡単な方法は Unicode文字を使って直接記述することなので、そのエンコードを決める必要があります。
全ての Python ドキュメントのソースファイルは UTF-8 エンコードでなければなりません。 そしてHTMLドキュメントもUTF-8で出力するのが良いでしょう。
reST ドキュメントをオーサリングするときに良く問題になることがあります: