早わかり reStructuredText

http://docutils.sourceforge.net/docs/user/rst/quickref.html
Being a cheat-sheet for reStructuredText
Updated $Date: 2019-09-30 13:36:39 +0200 (Mo, 30. Sep 2019) $

Copyright: このドキュメントはパブリックドメインです。

マークアップの完全な情報は reStructuredText ページにあります。このドキュメントはあくまで備忘録です。

ドキュメント内にある "(詳細)" リンクは完全な reStructuredText 仕様のHTML版へのリンクです。リンク切れがある場合は、 "Quick reStructuredText" を参照してください.

コンテンツ

インラインマークアップ

(詳細)

インラインマークアップは単語とフレーズの中に文字表現による装飾(イタリックや強調)と、機能性(ハイパーリンク等)を提供します。

プレーンテキスト 代表的な結果 注釈
*emphasis* emphasis Normally rendered as italics.
**strong emphasis** strong emphasis Normally rendered as boldface.
`interpreted text` (see note at right) The rendering and meaning of interpreted text is domain- or application-dependent. It can be used for things like index entries or explicit descriptive markup (like program identifiers).
``inline literal`` inline literal Normally rendered as monospaced text. Spaces should be preserved, but line breaks will not be.
reference_ reference A simple, one-word hyperlink reference. See Hyperlink Targets.
`phrase reference`_ phrase reference A hyperlink reference with spaces or punctuation needs to be quoted with backquotes. See Hyperlink Targets.
anonymous__ anonymous With two underscores instead of one, both simple and phrase references may be anonymous (the reference text is not repeated at the target). See Hyperlink Targets.
_`inline internal target` inline internal target A crossreference target within text. See Hyperlink Targets.
|substitution reference| (see note at right) The result is substituted in from the substitution definition. It could be text, an image, a hyperlink, or a combination of these and others.
footnote reference [1]_ footnote reference 1 See Footnotes.
citation reference [CIT2002]_ citation reference [CIT2002] See Citations.
http://docutils.sf.net/ http://docutils.sf.net/ A standalone hyperlink.

アスタリスク、バッククォート、垂直バー、アンダースコアはインラインの区切り文字として扱われます。 アスタリスク、バッククォート、垂直バーはクォートのように振る舞います。単語やフレーズの前後を囲み、その外側には空白文字や他のクォートが必要です。クォート内に空白文字だけで置くことはできません。 もし、インラインデリミタ文字をその文字自体として使いたい場合、 バックスラッシュでのエスケープ を行うか(例えば2重バッククォートでインラインリテラルとして)クォートしてください。

reStructuredText のインラインマークアップ仕様の詳細として、 開始文字と終了文字(インラインマークアップ区切り文字)として 以下のルールが適用されます:

  1. 開始文字はテキストブロックか、直前に空白か次のいずれかを置く: ' " ( [ { <
  2. 開始文字の直後には空白以外の文字が必要
  3. 終了文字の直前には空白以外の文字が必要
  4. 終了文字はテキストブロック(ドキュメントの終わり、または空行が続く)か、 直後に空白または次のいずれかを置く: ' " . , : ; ! ? - ) ] } / \ >
  5. 開始文字の直前が ' " ( [ { < のいずれかの場合、 続けてその文字に呼応する文字 ' " ) ] } > があってはならない
  6. 開始文字と終了文字の間には1つ以上の文字があること
  7. エスケープ されていないバックスラッシュが開始文字や終了文字の直前にあると、 インラインリテラルの終了文字以外は、マークアップとして解釈されなくなる

また、インラインマークアップはおそらくネスト(入れ子に)できません。 (インラインリテラルは他のインラインマークアップの区切り文字を含められますが、それはインラインマークアップとして解釈されません)

バックスラッシュでのエスケープ

(詳細)

reStructuredTextが持つマークアップの特別な機能性をバックスラッシュ ("\") によって上書きし、文字本来の表示できます。 バックスラッシュ自身をそのまま表示するには、バックスラッシュをバックスラッシュでエスケープします ("\\")。以下はエスケープの例です。

Raw reStructuredText 代表的な結果
*escape* ``with`` "\" escape with ""
\*escape* \``with`` "\\" *escape* ``with`` "\"

Pythonの文字列内で上記のようなreStructuredTextを書く場合は、 もちろん、バックスラッシュ自体のエスケープをしてバックスラッシュを reStructuredTextまで届ける必要があります。 raw文字列を使うとシンプルに実現できます。

Python string 代表的な結果
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.
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.

段落

(詳細)

プレーンテキスト 代表的な結果

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.

フィールドリストは拡張記法の一種です。ディレクティブのオプション指定や、データベースのレコードのように後で使うために定義します。フィールドリストは、2列のテーブルを出力するのにも使えます。

オプションリスト

(詳細)

プレーンテキスト 代表的な結果

-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

オプションとその説明の間には2つ以上の空白を置いてください。

リテラルブロック

(詳細)

プレーンテキスト 代表的な結果
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.

"doctest モジュールは、対話的 Python セッションのように見えるテキストを探し出し、セッションの内容を実行して、 そこに書かれている通りに振舞うかを調べます。" (doctestドキュメントより)

テーブル

(詳細)

reStructuredTextには、テーブルを表現する2つの文法があります。 グリッドテーブルは完璧ですが、書くのが面倒です。 シンプルテーブルは書くのが簡単ですが、結合セルを表現できないなどの制約があります。

プレーンテキスト 代表的な結果

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.

トランジションは小説などでよく見かけます。 文章と文章の間に1本~数本の区切り線を置いて、 文章、話題、時間、観点、感情の切り替わりを表現します。

明示的マークアップ

明示的マークアップブロックは、次のような文を置くために使います。 文章から浮いた文(脚注)、紙に印字されない表現(ハイパーリンクターゲット、コメント)、 特別な処理が必要な文(ディレクティブ)などです。 明示的マークアップは必ず、"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 [#]_.

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

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

.. [#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 symbol footnote
[†] 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".

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.


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

ハイパーリンクターゲット

(詳細)

外部ハイパーリンクターゲット

プレーンテキスト 代表的な結果
External hyperlinks, like Python_.

.. _Python: http://www.python.org/

短縮形式
External hyperlinks, like Python.
展開形式
External hyperlinks, like Python.


Python: http://www.python.org/

"短縮" はHTMLドキュメントでよく使われる表示です。 "展開" は印刷するドキュメントに適した表示で、リンクや脚注を明示的に表示します。 展開形式を強制的に使いたい場合は、 "target-notes" ディレクティブで指定します。

reStructuredTextには、埋め込みURI (詳細) 記法もあり、この記法は読みやすい書き方です。 ハイパーリンク参照とする文字列をバッククォートでカコミ、リンク先URIを直接埋め込みます。 以下の例は、上記の書き方と同じ意味で解釈されます。

プレーンテキスト 代表的な結果
External hyperlinks, like `Python
<http://www.python.org/>`_.
External hyperlinks, like Python.

内部ハイパーリンクターゲット

プレーンテキスト 代表的な結果
Internal crossreferences, like example_.

.. _example:

This is an example crossreference target.

短縮形式
Internal crossreferences, like example

This is an example crossreference target.

展開形式
Internal crossreferences, like example

example:
This is an example crossreference target.

無名ハイパーリンクターゲット

(詳細)

プレーンテキスト 代表的な結果
Python_ is `my favourite
programming language`__.

.. _Python: http://www.python.org/

__ Python_

Python is my favourite programming language.

2つ目の("__"で始まっている)ハイパーリンクターゲットは、 別のハイパーリンクターゲット("Python_"が指すPythonウェブサイト) を間接的に参照している無名ハイパーリンクターゲットです。 テキストの直後に2つのアンダースコアを付けると、無名ハイパーリンク参照になります。 無名ハイパーリンクターゲットを書くときは、ハイパーリンク参照のテキストをもう一度書く必要はありません。 このため、長いテキストをハイパーリンク参照にしたいときや、参照を再利用しない場合に有用です。 ただし、ハイパーリンクターゲットと参照の対がズレないように近くに書いておくべきでしょう。

暗黙的ハイパーリンクターゲット

(詳細)

セクションタイトルや脚注、引用は自動的にハイパーリンクターゲットになります (タイトルテキスト、脚注ラベル、引用ラベルがハイパーリンク参照名になります)。

プレーンテキスト 代表的な結果
Titles are targets, too
=======================
Implict references, like `Titles are
targets, too`_.
Titles are targets, too

Implict references, like Titles are targets, too.

ディレクティブ

(詳細)

ディレクティブは多目的に使える拡張の仕組みで、新しい機能を文法の拡張なしで導入できます。 標準ディレクティブの情報は全て reStructuredText ディレクティブにまとまっています。

プレーンテキスト 代表的な結果
For instance:

.. image:: images/ball1.gif

For instance:

ball1

置換定義

(詳細)

置換はインラインディレクティブのようなもので、画像や調整した文字列をインラインで埋め込みます。

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

.. |biohazard| 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.

助けを求める

DocutilsやreStructuredTextについて質問や助けが必要な方は、 Docutils-Users mailing listメッセージを投稿 してください。 DocutilsプロジェクトWebサイト にも情報があります。


Authors: Tibs (tibs@tibsnjoan.co.uk) and David Goodger (goodger@python.org)