ReStructuredText 入門

著者:Richard Jones
英語原版:A ReStructuredText Primer
バージョン:1.17
著作権:This document has been placed in the public domain.
翻訳者:瀬戸山春輝 haruki@planewave.org
翻訳著作権:クリエイティブ・コモンズ 帰属ライセンス

Contents

以下の文章中に "(quickref)" という形式のリンクがあります。これは、 Quick reStructuredText ユーザリファレンスへの相対リンクです。このリンクが 切れている場合は、 オンラインのクイックリファレンス を参照してください。

構造

まずはじめに、"Structured Text" (構造化されたテキスト)という呼び方には、 いくぶん不適切なところがあると指摘しておきます。実際には、首尾一貫したパターンを使う "Relaxed Text" (形式ばらないテキスト)とでも呼ぶべきものです。そのパターンを HTML コンバータで変換することで、WEB ブラウザで扱えるような「非常に構造化された テキスト」が生成されるのです。

最も分かり易くて基本的なパターンは、 パラグラフ(段落) (quickref) です。 (1つ以上の)空行で区分されたテキストのひとかたまりが、パラグラフとなります。 パラグラフは等しいインデントでなければなりません。つまり、パラグラフの 各行は左側が揃っていなければならないということです。また、インデントされた パラグラフは、引用のパラグラフに変換されます。 たとえば、

これはパラグラフです。とても
短いですね。

   このパラグラフは、インデントされたテキストで、
   通常、他のテキストの引用として扱われます。

これもパラグラフです。

結果は、

これはパラグラフです。とても 短いですね。

このパラグラフは、インデントされたテキストで、 通常、他のテキストの引用として扱われます。

これもパラグラフです。

テキストの装飾

(quickref)

パラグラフやその他のテキストでは、 斜体 としたい部分を "*斜体*" という形式で、 太字 としたい部分を "**太字**" という形式で マークアップします。

固定スペースで表示させたい場合は、"``2重バッククォート``" を使います。 2重バッククォートの内部では、文字装飾は行われません。 ですから、アスタリスク "*" などはそのままになります。

「特殊」文字をテキスト中で使いたい場合も、reStructuredText はスマートにできており、 問題はありません。たとえば、アスタリスク * を上手く扱いたい場合を例に取ります。 *アスタリスクに挟まれた* テキストを斜体に したくない ときには、 "\*" (quickref) と言うようにバックスラッシュ(日本語環境では円記号)を 前に置くか、2重バッククォートで以下のように囲むかして、 そのアスタリスクが特殊ではないことを示します。

``\*``

リスト

リストには、 番号付き箇条書き定義 の3種類があります。 すべてのリストは、パラグラフの左側を、リストの要素の最初の行とあわせることで、 複数パラグラフやサブリストを扱うことができます。

リストは、新しいパラグラフの始まりとなります。すなわち、空行の後にリストを書く 必要があります。

番号付き リスト (数、文字もしくはローマ数字、 quickref)

行を、ピリオド "." か閉じ括弧 ")" を付けた、もしくは括弧で囲んだ "( )" 数字か文字で始めます。以下の形式のすべてが認識されます。

1. 数字

A. 大文字の英字
   複数行も書けます。

   複数のパラグラフも!

a. 小文字の英字

   3. 違う番号から始まるサブリスト
   4. 番号が適切な順番になっているか確認してください。

I. 大文字のローマ数字

i. 小文字のローマ数字

(1) 数字

1) 数字

変換結果はこの通り(注意。ブラウザによっては、これらすべての形式の 番号付きリストがサポートされていない場合もあります。ですので、 上のように指定した効果が完全には表示されていないかも知れません)。

  1. 数字
  1. 大文字の英字 複数行も書けます。

    複数のパラグラフも!

  1. 小文字の英字
    1. 違う番号から始まるサブリスト
    2. 番号が適切な順番になっているか確認してください。
  1. 大文字のローマ数字
  1. 小文字のローマ数字
  1. 数字
  1. 数字
箇条書き リスト (quickref)

番号つきリストと似ていますが、行を "-" または "+", "*" の行頭記号で 始めます。

* 行頭記号 "*"

  - 行頭記号 "-"

    + サブリスト

  - 複数アイテム

変換結果はこの通り。

  • 行頭記号 "*"
    • 行頭記号 "-"
      • サブリスト
    • 複数アイテム
定義 リスト (quickref)

上の2つとは違って、定義リストは用語とその定義からなります。定義リストの様式は、

何を
  定義リストは用語と定義を関連付けます。

*どのように*
  用語は1行に収まるフレーズです。定義は、1つもしくは複数のパラグラフや
  その他の要素からなり、用語よりも深くインデントします。
  用語と定義との間に空行を入れてはいけません。

変換結果はこうなります。

何を
定義リストは用語と定義を関連付けます。
どのように
用語は1行に収まるフレーズです。定義は、1つもしくは複数のパラグラフや その他の要素からなり、用語よりも深くインデントします。 用語と定義との間に空行を入れてはいけません。

フォーマット済みテキスト

(quickref)

(コードのサンプルなど)フォーマット済みで、文字装飾を行ないたくないテキストを 扱う場合は、その直前のパラグラフを "::" で終えてください。フォーマット済みの ブロックは、インデントがそのフォーマット済みブロックの直前のパラグラフと同じに なったところで終わります。例を示しましょう。:

サンプル::

    空白文字や空行やすべてのマークアップ(たとえば *これ* や \これ)は
    そのままとなります。
  インデントレベルを下げました。
  (少しだけですが)

サンプル終わり

変換結果を示します。

サンプル:

  空白文字や空行やすべてのマークアップ(たとえば *これ* や \これ)は
  そのままとなります。
インデントレベルを下げました。
(少しだけですが)

サンプル終わり

"::" だけのパラグラフは、出力からは削除されます。:

::

    フォーマット済みテキストです。
    直前の "::" だけのパラグラフは削除されます。

変換結果はこの通り。

フォーマット済みテキストです。
直前の "::" だけのパラグラフは削除されます。

セクション

(quickref)

長い文章をセクション(章など)に別けるには、 セクションヘッダ を使います。 セクションヘッダとは、1行のテキストを、アンダーラインで、またはアンダーラインと オーバーラインで装飾したものです。ラインには、ダッシュ "-----" や 等号 "======" 、チルダ "~~~~~~" などの非アルファベットの文字 = - ` : ' " ~ ^ _ * + # < > を使用します。同じ文字を使用していても、 アンダーラインのみのものと、アンダーラインとオーバーライン両方を使ったものは 区別されます。アンダーラインやオーバーラインは、少なくともタイトルと同じ長さに してください。同じスタイルで装飾されたすべてのセクションは、同じレベルだと みなされますので、首尾一貫性を保つようにしてください。

第1章 タイトル
==============

セクション 1.1 タイトル
-----------------------

サブセクション 1.1.1 タイトル
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

セクション 1.2 タイトル
-----------------------

第2章 タイトル
==============

変換結果は、擬似 XML で表すと以下のようになります。

<section>
    <title>
        第1章 タイトル
    <section>
        <title>
            セクション 1.1 タイトル
        <section>
            <title>
                サブセクション 1.1.1 タイトル
    <section>
        <title>
            セクション 1.2 タイトル
<section>
    <title>
        第2章 タイトル

(この擬似 XML は、ネストをインデントで表し、終了タグがありません。セクションは 引用のブロック中に置けないため、他の例と異なり、実際の変換結果を示すことが できませんでした。具体的な例としては、この文書自体のソーステキストと変換結果とを 比較してみてください。)

セクションヘッダは、その名前をリンクのターゲットとして使用できます。リスト_ ヘッダにリンクしたい場合は、"リスト_"と書きます。ヘッダが、 ReStructuredText 入門 の様にスペースを含む場合は、 "`ReStructuredText 入門`_" とクオートする必要があります。

文書のタイトルとサブタイトル

文書全体のタイトルとセクションのタイトルとは区別され、異なった形式に変換 されます(たとえば、HTML ライタはデフォルトで、文書全体のタイトルを中央寄せに 表示します)。

reStructuredText において文書タイトルを記述するには、文書の最初に、ユニークな (文書の他の部分に出てこない)装飾形式で記述します。文書のサブタイトルを示すには、 文書タイトルの直後にまた別の形式を使用します。例を示します。

==============
 文書タイトル
==============
--------------
 サブタイトル
--------------

セクションのタイトル
====================

...

ここで、「文書タイトル」と「セクションのタイトル」とは同じ文字で装飾されていますが、 まったく異なるものとみなされています。見た目の美しさの観点から、(アンダーライン だけでなく)アンダーラインとオーバーライン両方を使う装飾が使われています。

画像

(quickref)

文書に画像を挿入するには、 image ディレクティブ を使います。 たとえば、

.. image:: images/biohazard.png

変換結果は、

images/biohazard.png

images/biohazard.png の部分が、ドキュメントで表示させたい画像のファイル名 です。イメージについて(形式やサイズなどの)制限はありません。画像が HTML で 表示される場合、追加の情報を付け加えることもできます。

.. image:: images/biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: alternate text

詳しい情報は、 画像ディレクティブの解説 を参照してください。

その他は?

この文書では、入門として、reStructuredText の最も一般的な機能について紹介 しました。しかし、reStructuredText には、もっと多くの機能があります。この文書の 次には、ユーザリファレンスである Quick reStructuredText を参照すると 良いでしょう。完全な詳細を知るには、 reStructuredText Markup Specification を参照してください。

Docutils および reStructuredText について質問があったり、援助が必要な場合は、 Docutils-Users mailing list に、 メールを出して みてください。 Docutils project web site にも、情報が掲載されています。

[1]相対リンクが切れている場合は、こちらのオンラインドキュメントを参照ください。 http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.