早わかり reStructuredText

Source URL:http://docutils.sourceforge.net/docs/user/rst/quickref.html
Updated:2009-07-14 16:05:34 +0200 (Die, 14 Jul 2009)
Copyright:This document has been placed in the public domain.

マークアップの完全な詳細は reStructuredText のページで 見つけることができます。この文書は単なるリマインダを意図しています。

“(details)” というリンクは完全な reStructuredText 仕様書 のHTML版を指しています。これらは相対リンクです; もしリンクが動作しない場合は、 Quick reStructuredText のマスタ文書を使ってください。

インラインマークアップ

インラインマークアップは、文章中の単語や文節に文字スタイル(斜体や太字等)と機能(ハイパーリンク等)を与えます。

インラインマークアップ
プレーンテキスト 表示 ノート
*強調*
強調 イタリック(斜体)として表示されます
**強い強調**
強い強調 ボールド(太字)として表示されます
`用語テキスト`
用語テキスト ドメイン又はアプリケーション固有の意味をもつテキストとして表示されます。 索引のエントリや(プログラム識別子のような)明示的記述的マークアップとして利用できます
``インラインリテラル``
インラインリテラル 等幅テキストとして表示されます。空白(スペース)は保持されますが、改行は保持されません
reference_
reference シンプルな、1ワードのハイパーリンク参照です。 ハイパーリンクターゲット を参照して下さい
`フレーズ参照`_
フレーズ参照 空白や記号を伴うハイパーリンク参照はバッククォートで括る必要があります。 ハイパーリンクターゲット を参照して下さい
anonymous__
anonymous ハイパーリンク参照のアンダースコアが2つの場合は、匿名参照です。 ハイパーリンクターゲット を参照して下さい
_`インライン内部ターゲット`
インライン内部ターゲット テキストの相互参照をします。 ハイパーリンクターゲット を参照して下さい
|置換参照|
(右のノート参照) 置換定義で定義された内容に置換されます。 テキスト、画像、ハイパーリンクもしくはそれらを組み合わせたものを 置き換えることができます
脚注参照 [1]_
脚注参照 脚注参照 を参照してください
引用参照 [CIT2002]_
引用参照 引用参照 を参照してください
http://docutils.sf.net/
http://docutils.sf.net/ 一般的なハイパーリンクです

アスタリスク (‘*’) 、バッククォート (‘`’) 、バーティカルバー (‘|’) 及び アンダースコア (‘_’) はインラインの区切り文字です。 アスタリスク、バッククォート及びバーティカルバーは引用符のようにマークアップする 単語やフレーズを対応する記号で囲みます。空白や他の引用符はそれらの外にある必要が あり、引用符の直ぐ内側に空白を含めることはできません。 もし文字そのものとしてこれらインライン区切り文字を利用する場合には、 エスケープする (バックスラッシュを用いる) か、それらを引用 (二重バッククォートを 用いる、すなわちインラインリテラルを利用する) します。

バックスラッシュによるエスケープ

reStructuredText は特別な意味をもつマークアップ文字を上書きして、文字そのものを 用いるためにバックスラッシュ (‘\’) を使います。 バックスラッシュそのものを使うには、バックスラッシュでエスケープします (‘\\’) 。

元のreStructuredText 表示結果
*escape* ``with`` "\"
escape with “”
\*escape* \``with`` "\\"
*escape* ``with`` “\”

もちろん、Pythonの文字列でも正しく reStructuredText になるように、 全てのバックスラッシュをエスケープする必要があります。

Pythonの文字列 表示結果
r"""\*escape* \`with` "\\""""
*escape* ``with`` “\”
"""\\*escape* \\`with` "\\\\""""
*escape* ``with`` “\”
"""\*escape* \`with` "\\""""
escape with “”

セクション構造

プレーンテキスト 表示結果
=====
Title
=====

Subtitle
--------

Titles are underlined (or over- 
and underlined) with a printing 
nonalphanumeric 7-bit ASCII 
character. Recommended choices 
are "``= - ` : ' " ~ ^ _ * + # < >``". 
The underline/overline must be at 
least as long as the title text. 

A lone top-level (sub)section 
is lifted up to be the document's 
(sub)title.

Titles are underlined (or over- and underlined) with a printing nonalphanumeric 7-bit ASCII character. Recommended choices are “= - ` : ' " ~ ^ _ * + # < >”. The underline/overline must be at least as long as the title text.

A lone top-level (sub)section is lifted up to be the document’s (sub)title.

段落

プレーンテキスト 表示結果
This is a paragraph.

Paragraphs line up at their left 
edges, and are normally separated 
by blank lines.

This is a paragraph.

Paragraphs line up at their left edges, and are normally separated by blank lines.

箇条書きリスト

プレーンテキスト 表示結果
Bullet lists:

- This is item 1 
- This is item 2

- Bullets are "-", "*" or "+". 
  Continuing text must be aligned 
  after the bullet and whitespace.

Note that a blank line is required 
before the first item and after the 
last, but is optional between items.

Bullet lists:

  • This is item 1
  • This is item 2
  • Bullets are “-”, “*” or “+”. Continuing text must be aligned after the bullet and whitespace.

Note that a blank line is required before the first item and after the last, but is optional between items.

列挙リスト

プレーンテキスト 表示結果
Enumerated lists:

3. This is the first item 
4. This is the second item 
5. Enumerators are arabic numbers, 
   single letters, or roman numerals 
6. List items should be sequentially 
   numbered, but need not start at 1 
   (although not all formatters will 
   honour the first index). 
#. This item is auto-enumerated

Enumerated lists:

  1. This is the first item
  2. This is the second item
  3. Enumerators are arabic numbers, single letters, or roman numerals
  4. List items should be sequentially numbered, but need not start at 1 (although not all formatters will honour the first index).
  5. This item is auto-enumerated

定義リスト

プレーンテキスト 表示結果
Definition lists: 

what 
  Definition lists associate a term with 
  a definition. 

how 
  The term is a one-line phrase, and the 
  definition is one or more paragraphs or 
  body elements, indented relative to the 
  term. Blank lines are not allowed 
  between term and definition.

Definition lists:

what
Definition lists associate a term with a definition.
how
The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition.

フィールドリスト

プレーンテキスト 表示結果
:Authors: 
    Tony J. (Tibs) Ibbs, 
    David Goodger
    (and sundry other good-natured folks)

:Version: 1.0 of 2001/08/08 
:Dedication: To my father.
Authors:Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks)
Version:1.0 of 2001/08/08
Dedication:To my father.

オプションリスト

プレーンテキスト 表示結果
-a            command-line option "a" 
-b file       options can have arguments 
              and long descriptions 
--long        options can be long also 
--input=file  long options can also have 
              arguments 
/V            DOS/VMS-style options too
-a command-line option “a”
-b file options can have arguments and long descriptions
--long options can be long also
--input=file long options can also have arguments
/V DOS/VMS-style options too

リテラルブロック

プレーンテキスト 表示結果
A paragraph containing only two colons 
indicates that the following indented 
or quoted text is a literal block. 

:: 

  Whitespace, newlines, blank lines, and 
  all kinds of markup (like *this* or 
  \this) is preserved by literal blocks. 

  The paragraph containing only '::' 
  will be omitted from the result. 

The ``::`` may be tacked onto the very 
end of any paragraph. The ``::`` will be 
omitted if it is preceded by whitespace. 
The ``::`` will be converted to a single 
colon if preceded by text, like this:: 

  It's very convenient to use this form. 

Literal blocks end when text returns to 
the preceding paragraph's indentation. 
This means that something like this 
is possible:: 

      We start here 
    and continue here 
  and end here. 

Per-line quoting can also be used on 
unindented literal blocks:: 

> Useful for quotes from email and 
> for Haskell literate programming.

A paragraph containing only two colons indicates that the following indented or quoted text is a literal block.

Whitespace, newlines, blank lines, and
all kinds of markup (like *this* or
\this) is preserved by literal blocks.

The paragraph containing only '::'
will be omitted from the result.

The :: may be tacked onto the very end of any paragraph. The :: will be omitted if it is preceded by whitespace. The :: will be converted to a single colon if preceded by text, like this:

It's very convenient to use this form.

Literal blocks end when text returns to the preceding paragraph’s indentation. This means that something like this is possible:

    We start here
  and continue here
and end here.

Per-line quoting can also be used on unindented literal blocks:

> Useful for quotes from email and
> for Haskell literate programming.

ラインブロック

プレーンテキスト 表示結果
| Line blocks are useful for addresses, 
| verse, and adornment-free lists. 
| 
| Each new line begins with a 
| vertical bar ("|"). 
|     Line breaks and initial indents 
|     are preserved. 
| Continuation lines are wrapped 
  portions of long lines; they begin 
  with spaces in place of vertical bars.
Line blocks are useful for addresses,
verse, and adornment-free lists.

Each new line begins with a
vertical bar (“|”).
Line breaks and initial indents
are preserved.
Continuation lines are wrapped portions of long lines; they begin with spaces in place of vertical bars.

引用ブロック

プレーンテキスト 表示結果
Block quotes are just:

    Indented paragraphs,

        and they may nest.

Block quotes are just:

Indented paragraphs,

and they may nest.

Doctestブロック

プレーンテキスト 表示結果
Doctest blocks are interactive 
Python sessions. They begin with 
"``>>>``" and end with a blank line.

>>> print "This is a doctest block." 
This is a doctest block.

Doctest blocks are interactive Python sessions. They begin with “>>>” and end with a blank line.

>>> print "This is a doctest block."
This is a doctest block.

テーブル

プレーンテキスト 表示結果
Grid table:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

Grid table:

Header 1 Header 2 Header 3
body row 1 column 2 column 3
body row 2 Cells may span columns.
body row 3 Cells may span rows.
  • Cells
  • contain
  • blocks.
body row 4
Simple table:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False 
True   False  True 
False  True   True 
True   True   True 
=====  =====  ======

Simple table:

Inputs Output
A B A or B
False False False
True False True
False True True
True True True

切り替え

プレーンテキスト 表示結果
A transition marker is a horizontal line 
of 4 or more repeated punctuation 
characters.

------------

A transition should not begin or end a 
section or document, nor should two 
transitions be immediately adjacent.

A transition marker is a horizontal line of 4 or more repeated punctuation characters.

A transition should not begin or end a section or document, nor should two transitions be immediately adjacent.

明示的マークアップ

明示的マークアップブロックは注釈 (脚注)、直接的な紙媒体を持たないもの (ハイパーリンクターゲット、コメント)、特別な処理が必要なもの (ディレクティブ)を 構成するために使います。これらはすべて2つのピリオドと空白、いわゆる “明示的なマークアップの開始” で始まります。

脚注参照

プレーンテキスト 表示結果
Footnote references, like [5]_. 
Note that footnotes may get 
rearranged, e.g., to the bottom of 
the "page".

.. [5] A numerical footnote. Note 
   there's no colon after the ``]``.
   

Footnote references, like [5]. Note that footnotes may get rearranged, e.g., to the bottom of the “page”.

[5]A numerical footnote. Note there’s no colon after the ].
Autonumbered footnotes are 
possible, like using [#]_ and [#]_.

They may be assigned 'autonumber 
labels' - for instance, 
[#fourth]_ and [#third]_.


.. [#] This is the first one. 
.. [#] This is the second one.
.. [#third] a.k.a. third_
.. [#fourth] a.k.a. fourth_

Autonumbered footnotes are possible, like using [1] and [2].

They may be assigned ‘autonumber labels’ - for instance, [4] and [3].

[1]This is the first one.
[2]This is the second one.
[3]a.k.a. third
[4]a.k.a. fourth
Auto-symbol footnotes are also 
possible, like this: [*]_ and [*]_.

.. [*] This is the first one. 
.. [*] This is the second one.

Auto-symbol footnotes are also possible, like this: [*] and [†].

[*]This is the first one.
[†]This is the second one.

自動採番の脚注の番号は、参照される順番ではなく脚注の (記述の) 順番で決まります。 自動採番の脚注をラベルなしで使う場合、参照と脚注は相互に同じ順番になっている 必要があります。自動シンボルの脚注の場合も同様です。

引用参照

プレーンテキスト 表示結果
Citation references, like [CIT2002]_. 
Note that citations may get 
rearranged, e.g., to the bottom of 
the "page".

.. [CIT2002] A citation 
   (as often used in journals).

Citation labels contain alphanumerics, 
underlines, hyphens and fullstops. 
Case is not significant.

Given a citation like [this]_, one 
can also refer to it like this_.

.. [this] here.

Citation references, like [CIT2002]. Note that citations may get rearranged, e.g., to the bottom of the “page”.

[CIT2002]A citation (as often used in journals).

Citation labels contain alphanumerics, underlines, hyphens and fullstops. Case is not significant.

Given a citation like [this], one can also refer to it like this.

[this]here.

ディレクティブ

ディレクティブは汎用の拡張メカニズムで、新しい文法を追加することなく 新しい構造のサポートを追加する方法です。 標準のディレクティブの説明は reStructuredText Derectives を参照してください。

プレーンテキスト 表示結果
.. image:: _static/image/ball1.gif
_images/ball1.gif

置換参照と定義

置換は画像や任意の構造物をテキストに埋め込む、インラインディレクティブのようなものです。

プレーンテキスト 表示結果
The |biohazard| symbol must be used on containers used to dispose of medical waste.

.. |biohazard| image:: _static/image/biohazard.png
The biohazard symbol must be used on containers used to dispose of medical waste.

コメント

明示的マークアップで始まっていて上述のいずれの文法も使っていない構造体は 全てコメントです。

プレーンテキスト 表示結果
.. This text will not be shown 
   (but, for instance, in HTML might be 
   rendered as an HTML comment)
An "empty comment" does not 
consume following blocks. 
(An empty comment is ".." with 
blank lines before and after.)

..

        So this block is not "lost", 
        despite its indentation.

An “empty comment” does not consume following blocks. (An empty comment is ”..” with blank lines before and after.)

So this block is not “lost”, despite its indentation.