S-JIS[2012-04-22/2012-05-09] 変更履歴
Sphinxで使われるreStructuredTextの構文のメモ。
|
reStructuredText（reST）では記号を使って構造を作っていくが、空行やインデント（行頭の空白）にも意味が有る。
基本的に、入れ子になったブロック（段落）では内側の文章のインデント（空白の桁数）を統一し、同じ位置（桁）から文章が始まるようにする。
同じ構造を作るにも、何種類かの記号を使うことが出来るものがある。
その文書内で使う記号に統一が取れていれば、どれでもいい。
適当にHTMLと対比させるとこんな感じ？
| HTML | reST | 備考 | |
|---|---|---|---|
| 見出し | <h1> |
==== |
どの記号だと<h1>相当、と決まっているわけではない。 また、記号の文字数にルールがある。 |
| 目次 | .. toctree:: |
ファイル内の見出しに基づいて目次を作成する。 ファイルには別ページのファイル名（拡張子抜き）を指定する。 |
|
| 段落 | <p>文章</p> |
空行で開始し、空行で終わる範囲。 | |
| 改行 | 文章1<br> |
| 文章1 |
行頭に「|」を置く。「|」の直後にスペースを入れる必要がある。 |
| 番号なしリスト | <ul> |
* 文章 |
同じレベルの箇条書きには同じ記号を使う。 |
| 番号つきリスト | <ol> |
1. 文章 |
ピリオドや括弧閉じで順序番号つきの箇条書きになる。 各番号は増加した値を自分で書く必要がある。 （reSTはテキストのまま読んでも分かるようにする思想の為） 数字やアルファベット、ローマ数字が可能。 |
| 定義・説明文 | <dl> |
用語 |
用語の次の行にインデントを付けて説明文を書く。 インデントの空白文字の文字数は何文字でもいい。 |
| 整形済みテキスト | <pre>文章1 |
:: |
「::」の下に一行空けて、インデントを付けて文章を書く。 |
タイトル:: |
「::」の前に表題を書くと、「タイトル:」の様に出力される。 |
||
.. sourcecode:: java |
ソースコード用の整形。 「 ::」の後ろに対象言語を書くことで、その言語のキーワードに色が付く。インデントは「sourcecode」の位置に合わせる。 「 :linenos:」を入れると、行番号も出力される。なお、古いバージョンのSphinxでは「sourcecode」でなく「code-block」だったらしい。 |
||
.. sourcecode:: java |
|||
| 水平線 | <hr> |
---- |
見出しに使う文字を4つ以上並べ、前後に空行を入れると水平線になる。[2012-05-09] |
| 強調表示（ボールド） | これは<strong>強調</strong>です |
これは **強調** です |
「**」で囲む。 |
| 斜体（イタリック） | これは<em>斜体</em>です |
これは *斜体* です |
「*」で囲む。 |
| 外部リンク | これは<a href="URL">リンク</a>です |
これは `リンク <URL>`_ です |
バッククォートで囲む。末尾にアンダースコアを付ける。 URLを「<」「>」で囲む。[2012-05-04] |
段落の見出し（HTMLのh1,h2,…相当）には「=」や「-」「#」「*」「^」「~」「"」といった記号を使う。
見出しの文章の上下にその記号を並べる（上下で囲むイメージ）か、文章の下に記号を並べる（アンダーラインの様なイメージ）。
どちらの場合でも、記号は文章の文字数以上にする必要がある。（いわゆる半角文字に換算した文字数っぽい）
========== 見出しの例 ==========
見出しの例2 ===========
見出し！ --------
どれがh1でどれがh2になるかという事については、そのファイル内で出てきた順。
一番最初に出た形式がh1で、次に出た形式がh2で、…となる。
同じ記号でも、上下に書くのと下に書くのとでは別レベルとして扱われる。
どういう形式（記号）を使っても良いが、そのファイル内では同一レベルは同一形式を使うよう統一する必要がある。
番号なしリストは「*」「+」「-」を使う。
各行は連続して書いてよい（空行をはさむ必要は無い）。
* あああ * いいい * うう |
|
内訳のブロックを作りたい場合は、一行空けてインデントする。使う記号は同じでも違ってもよい。
（インデントを付けずに記号だけ変えても、同レベルの別ブロックとなるだけで、内訳にはならない）
インデントは、記号直後の文章の開始桁に合わせる。
* あああ * あいうえお * あかさたな * いいい * いい |
|
* あああ * いいい + ううう + えええ |
|
文章内で改行したい場合は、各文章の先頭に「|」を入れる。
* | あああ | いいい * ううう えええ | おおお1 | おおお2 |
|
番号つきリストは数値やアルファベットの後ろにピリオドや括弧閉じを付けるか、丸括弧で囲む。
値は自分で増やして付ける必要がある。
1. 文章 2. 文章 |
|
(1) 文章 (2) 文章 |
|
1) 文章 2) 文章 |
|
A. 文章 B. 文章 |
|
I. 文章 II. 文章 III. 文章 IV. 文章 |
|
1. 文章 1) 文章 2) 文章 2. 文章 (1) 文章 (2) 文章 |
|
1. | 文章A | 文章B 2. 文章 |
|