目次

前のトピックへ

2. スタイルガイド

次のトピックへ

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

このページ

3. reStructuredText の基礎

この節は reStructuredText (reST) のコンセプトと文法の要約です。ドキュメント作者の生産性のために十分な情報を提供することに注目しています。 reST はシンプルで、出しゃばらないマークアップ言語として設計されたので、この文章はあまり長くありません。

参考

The authoritative reStructuredText User Documentation.

3.1. 段落 (Paragraphs)

段落は reST においてもっとも基本的なブロックです。一行以上の空行で区切られただけのテキストの固まりが段落になります。 Python と同じく、 reST ではインデントは重要な意味を持つので、同じ段落に属す行は全て同じインデントレベルで左揃えする必要があります。

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

reST 標準のインラインマークアップは非常にシンプルです。

  • アスタリスク一つ: *text* を強調 (斜体) に、
  • アスタリスク二つ: **text** を強い強調 (太字) に、
  • バッククォート: ``text`` をサンプルコードに、

使ってください。

もしアスタリスクやバッククォートが通常のテキストの中で出てきて、インラインマークアップ用の区切り文字と混合する場合は、バックスラッシュ(訳注: 日本語フォントでは、一般的に円記号になります)でエスケープする必要があります。

インラインマークアップの幾つかの制限に気をつけてください:

  • ネストできません。
  • マークアップされる内容の先頭や終端に空白文字があってはなりません: * text* は間違いです。
  • マークアップの外側は、non-word 文字で囲まれていなければなりません。必要な場合はバックスラッシュでエスケープしたスペースを使ってください: thisis\ *one*\ word

これらの制限は将来のバージョンの docutils で解除されるかもしれません。

reST は独自の “interpreted text roles” に対応していて、囲まれたテキストを専用の方法で解釈することができます。別の節で解説しますが、Sphinx はこれを、意味に基づくマークアップと識別子のクロスリファレンスのために利用しています。 “interpreted text roles” の一般的な文法は :rolename:`内容` になります。

3.3. リストとクォート (Lists and Quotes)

リストの表現は自然です: 段落の最初にアスタリスクをおいて、適切にインデントするだけです。番号付きリストも同じで、 # 記号を使えば自動的にナンバリングされます:

* これは番号なしリストです。
* リストの要素は二つあり、二つ目は
  二行使用しています。

#. これば番号付きリストです。
#. こちらも要素が二つあります。

リストはネストさせることもできます。親になるリスト要素との間に空行が必要なことに気をつけてください:

* これは
* リストで

  * ネストされたリストと
  * 子要素があります。

* そしてここは親のリストの続きです。

定義リストは次のようにして作ります:

単語 (行の終わりまで)
   単語の定義。インデントされている必要がある。

   複数の段落を持つことも可能。

次の単語
   定義。

定義の部分は周りの段落よりも深くインデントします。

3.4. ソースコード (Source Code)

リテラルコードブロックは、特別なマーカー :: で終わる段落の次に始まります。リテラルブロックはインデントしなければなりません。

これは通常の段落です。次の段落はコードサンプルです::

   ここには、インデントの除去以外の
   処理が行われません。

   複数行にまたがることもできます。

ここでまた通常の段落になります。

:: マーカーの処理はスマートです:

  • 単体で段落になっていた場合は、その段落はドキュメントから完全に除去されます。
  • マーカーの前に空白があれば、マーカーは削除されます。
  • マーカーの前が空白でなければ、マーカーはコロン一つに置き換えられます。

なので、上の例での最初の段落の二つ目の文は、 “次の段落はコードサンプルです:” と出力されます。

3.6. 明示的なマークアップ (Explicit Markup)

reST において、 “明示的なマークアップ (explicit markup)” は、脚注、特別なハイライト付きの文、コメント、一般的な指定のために利用されます。

明示的なマークアップのブロックは、 .. に空白が続いたものが行頭にあるときに始まり、次の段落が同じインデントになるところで終わります。 (明示的なマークアップと通常の段落の間には空行が必要です。すこし複雑に思えるかもしれませんが、ドキュメントを書くときには十分に直感的です。)

3.7. ディレクティブ (Directives)

ディレクティブは一般的な、明示的なマークアップを行うブロックです。 role のような reSTの拡張メカニズムの一つで、 Sphinx はディレクティブを多用しています。

基本的に、ディレクティブは、名前、引数、オプション、内容で構成されます。 (この XXX を覚えておいてください。次の章でカスタムディレクティブを説明するときに出てきます。) 次の例を見てください

.. function:: foo(x)
              foo(y, z)
   :bar: no

   ユーザーから入力されたテキスト一行を返す.

function はディレクティブの名前です。ここでは引数が二つあり、一つは一行目の残りの部分で、もう一つは次の行です。オプションも一つ、 bar があります。 (ごらんの通り、オプションは引数の行のすぐ次の行にあり、コロンで示されます.)

一行の空行を挟んでディレクティブの内容が続きます。内容はディレクティブの開始位置と同じ場所までインデントされます。

3.8. 脚注 (Footnotes)

脚注を使うときは、 [#]_ を使って脚注を入れる場所を示し、脚注の内容はドキュメントの最後に、次の例のように、”Footnotes” [1] という rubric ヘッダの後に書きます。

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] 最初の脚注の内容
.. [#] 二つ目の脚注の内容

3.9. コメント (Comments)

(上の脚注のような)有効なマークアップになっていない、全ての明示的なマークアップブロックは、コメントとして扱われます。

3.10. ソースのエンコード (Source encoding)

em dash や copyright sign のような特別な文字を reST に含める最も簡単な方法は Unicode文字を使って直接記述することなので、そのエンコードを決める必要があります。

全ての Python ドキュメントのソースファイルは UTF-8 エンコードでなければなりません。そしてHTMLドキュメントもUTF-8で出力するのが良いでしょう。

3.11. 判っていること

reST ドキュメントをオーサリングするときに良く問題になることがあります:

  • インラインマークアップの区切り: 上で述べたように、インラインマークアップは囲っているテキストと non-word 文字で区切られています。スペースを囲むときにはエスケープが必要になります。

注記

[1]訳注:Sphinx 1.0 以降では日本語で Footnotes の代わりに “注記” も許容されるようです。