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 のインラインマークアップ仕様の詳細として、 開始文字と終了文字(インラインマークアップ区切り文字)として 以下のルールが適用されます:
また、インラインマークアップはおそらくネスト(入れ子に)できません。 (インラインリテラルは他のインラインマークアップの区切り文字を含められますが、それはインラインマークアップとして解釈されません)
(詳細)
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
|
This is a paragraph. Paragraphs line up at their left edges, and are normally separated by blank lines. |
(詳細)
プレーンテキスト | 代表的な結果 |
---|---|
Bullet lists:
- This is item 1
- Bullets are "-", "*" or "+".
Note that a blank line is required
| Bullet lists:
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
| Enumerated lists:
|
(詳細)
プレーンテキスト | 代表的な結果 |
---|---|
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:
|
(詳細)
プレーンテキスト | 代表的な結果 | ||||||||
---|---|---|---|---|---|---|---|---|---|
:Authors:
Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) :Version: 1.0 of 2001/08/08
|
|
フィールドリストは拡張記法の一種です。ディレクティブのオプション指定や、データベースのレコードのように後で使うために定義します。フィールドリストは、2列のテーブルを出力するのにも使えます。
(詳細)
プレーンテキスト | 代表的な結果 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
-a command-line option "a"
|
|
オプションとその説明の間には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:
|
ディレクティブの後に引用ブロックを置くような、連続するインデント文を分割して扱いたい場合は、 空のコメントを間に置いてください。
(詳細)
プレーンテキスト | 代表的な結果 |
---|---|
Doctest blocks are interactive
>>> print "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."
|
"doctest モジュールは、対話的 Python セッションのように見えるテキストを探し出し、セッションの内容を実行して、 そこに書かれている通りに振舞うかを調べます。" (doctestドキュメントより)
(詳細)
reStructuredTextには、テーブルを表現する2つの文法があります。 グリッドテーブルは完璧ですが、書くのが面倒です。 シンプルテーブルは書くのが簡単ですが、結合セルを表現できないなどの制約があります。
プレーンテキスト | 代表的な結果 | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Grid table: +------------+------------+-----------+
|
Grid table:
| ||||||||||||||||||
Simple table: ===== ===== ======
|
Simple table:
|
(詳細)
プレーンテキスト | 代表的な結果 |
---|---|
A transition marker is a horizontal line
------------ A transition should not begin or end a
|
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
|
Footnote references, like 5.
Note that footnotes may get rearranged, e.g., to the bottom of
the "page".
| ||||||||||
Autonumbered footnotes are
possible, like using [#]_ and [#]_. .. [#] This is the first one.
They may be assigned 'autonumber
.. [#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.
| ||||||||||
Auto-symbol footnotes are also
possible, like this: [*]_ and [*]_. .. [*] This is the first one.
|
Auto-symbol footnotes are also
possible, like this: *
and †.
|
オートナンバー型脚注は、脚注の登場順に番号が振られます。 脚注参照の登場順ではありません。 オートナンバー型脚注への脚注参照をラベル無し("[#]_")で行う場合、 参照と定義の登場順を一致させる必要があります。 オートシンボル脚注("[*]_")でも同様です。
(詳細)
プレーンテキスト | 代表的な結果 | ||||||
---|---|---|---|---|---|---|---|
Citation references, like [CIT2002]_.
Note that citations may get rearranged, e.g., to the bottom of the "page". .. [CIT2002] A citation
Citation labels contain alphanumerics,
Given a citation like [this]_, one
.. [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.
|
(詳細)
プレーンテキスト | 代表的な結果 | |||||
---|---|---|---|---|---|---|
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. |
| ||
|
(詳細)
プレーンテキスト | 代表的な結果 |
---|---|
Python_ is `my favourite
programming language`__. .. _Python: http://www.python.org/ __ Python_ |
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:
|
(詳細)
置換はインラインディレクティブのようなもので、画像や調整した文字列をインラインで埋め込みます。
プレーンテキスト | 代表的な結果 |
---|---|
The |biohazard| symbol must be
used on containers used to
dispose of medical waste.
.. |biohazard| image:: biohazard.png |
The 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",
|
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)