reStructuredText入門

この節では，reStructuredText(reST)の概念と構文について簡単に紹介します．これは，文書を効率よく作成するための十分な情報を作成者に提供することを目的としています．reSTは単純で目立たないマークアップ言語として設計されているため，それほど時間はかかりません．

参考

権威ある reStructuredText User Documentation ．

段落

段落は，reST文書の最も基本的なブロックです．段落は，1行以上の空白行で区切られたテキストの集まりです．Pythonと同様，reSTではインデントが重要なので，同じ段落のすべての行を同じレベルのインデントに左揃えにする必要があります．

インラインマークアップ

標準のreSTインラインマークアップは非常に簡単です．

  • 1つのアスタリスク *text* は強調(イタリック体)です

  • 2つのアスタリスク: **text** が(太字)強強調で使われています．

  • 逆引用符: サンプルコードでは ``text`` ．

実行中のテキストにアスタリスクまたはバッククォートが表示され，インラインのmarkupデリミタと混同される可能性がある場合は，バックスラッシュでエスケープする必要があります．

このmarkupにはいくつかの制限があることに注意してください．

  • ネストされていない可能性があります．

  • contentは空白で始まったり終わったりしません． * text* は間違っています．

  • 周囲のテキストと単語以外の文字で区切る必要があります．これを回避するには，バックスラッシュでエスケープしたスペース thisis\ *one*\ word を使用します．

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

reSTでは，囲まれたテキストを特定の方法で解釈する必要があることを意味するカスタムの "解釈されたテキストの役割"' も使用できます．Sphinxはこれを使用して，適切なセクションで説明されているように，セマンティックmarkupと識別子の相互参照を提供します．一般的な構文は :rolename:`content` です．

リストと引用

リストのマークアップは自然なもので，段落の先頭にアスタリスクを付け，適切にインデントします．番号付きリストについても同様です． # 符号を使って自動番号付けすることもできます．

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

ネストされたリストも使用できますが，次のように親リスト項目から空白行で区切る必要があります．

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

定義リストは次のように作成されます．

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

段落は，周囲の段落よりもインデントされて引用されます．

ソースコード

文字コードブロックは，段落の末尾に特殊記号 :: を付けることで導入されます．リテラルブロックは次のようにインデントする必要があります．

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

:: マーカーの取り扱いは賢明です．

  • 単独の段落として出現する場合は，その段落は文書から完全に除外されます．

  • 先頭に空白がある場合，マーカーは削除されます．

  • 先頭に空白以外の文字がある場合，マーカーはコロンに置き換えられます．

このようにすると，上記の例の最初の段落の2番目の文は "次の段落はコードサンプルです" と表示されます．

セクション

セクションヘッダーは，セクションタイトルに句読点文字(必要に応じて)を，少なくとも次のテキストと同じ長さで下線を付けることによって作成されます．

=================
This is a heading
=================

通常，構造は見出しの連続から決定されるため，特定の文字に割り当てられる見出しレベルはありません．ただし，Pythonのマニュアルでは，次の表記規則を使用します．

  • 上線で # とすると部になります

  • 上線で * とすると章になります

  • セクションでは =

  • サブセクションの場合は -

  • サブサブセクションの場合は ^

  • " によりパラグラフとなります

陽なマークアップ

reSTでは，脚注，特別に強調表示された段落，コメント，汎用ディレクティブなど，特別な処理が必要なほとんどの構文に対して "明示的マークアップ" を使用します．

明示的なmarkupブロックは， .. その後に空白が続き，同じレベルのインデントで次の段落で終わります．(明示的なmarkupと通常の段落の間に空白行が必要です．これは少し複雑に聞こえるかもしれませんが，書くときには直感的に理解できます．)

指示

ディレクティブは，明示的markupの一般的なブロックです．役割の他に，reSTはreSTの拡張メカニズムの1つであり，Sphinxはこれを多用します．

基本的に，ディレクティブは名前，引数，オプション，および内容で構成されます．(次の章では，この用語を使用してカスタムディレクティブを説明します．)この例を見てみましょう．

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

   Return a line of text input from the user.

function はディレクティブ名です．ここでは，最初の行と二番目の行の残りの部分と，一つの選択肢である bar (ご覧のように，オプションは引数の直後の行に与えられ，コロンで示されています．)が与えられています．

ディレクティブの内容は空白行の後に続き，ディレクティブの開始に対してインデントされています．

脚注

脚注の場合は， [#]_ を使用して脚注の位置をマークし，次のように "脚注" のルビ見出しの後に脚注本文を追加します．

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

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

また，脚注に番号を明示的に付けることもできます．

コメント

(上の脚注のように)有効なmarkup構造ではないすべての明示的なmarkupブロックは，コメントと見なされます．

ソースエンコーディング

emダッシュや著作権記号などの特殊文字をreSTに含める最も簡単な方法は，Unicode文字として直接書くことなので，エンコーディングを指定する必要があります．

すべてのPythonドキュメントのソースファイルはUTF-8エンコーディングである必要があり，それらから書かれたHTMLドキュメントも同じエンコーディングになります．

Gotchas

reSTドキュメントのオーサリング時によく発生する問題がいくつかあります．

  • インラインmarkupの分離: 前述のように，インライン・markupスパンは，非単語文字によって周囲のテキストと分離されている必要があります．これを回避するには，エスケープされたスペースを使用する必要があります．