reStructuredText 入門

Author:David Goodger
Contact:docutils-develop@lists.sourceforge.net
Revision:$Revision: 7302 $
Date:$Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $
Copyright:

このドキュメントは、パブリック ドメインで公開されています。

reStructuredText は読み易く、見たままのものが得られる、プレーンテキストのマークアップ文法およびパーサシステムです。インラインの(Python の docstring のような)プログラムドキュメントを書いたり、シンプルな web ページをさっと作ったり、個別のドキュメントを作成するのにも便利です。 reStructuredTextStructuredTextSetext 軽量マークアップシステムの改善提案であり、再解釈なのです。

reStructuredText は特定のアプリケーションドメインのための拡張として設計されています。パーサは Docutils のコンポーネントです。

このドキュメントでは reStructuredText のゴールを定義し、プロジェクトの歴史をご紹介します。このドキュメントも reStructuredText で書かれており、その使い方の例として役割を果たします。 reStructuredText の使い方の丁寧な概要については、 reStructuredText 入門書を読んでください。 早わかり reStructuredText ユーザリファレンスも便利です。 reStructuredText マークアップ仕様 は最も信頼のおけるリファレンスです。StructuredText における問題点 の分析もあります。

ReStructuredText の web ページは http://docutils.sourceforge.net/rst.html です。

ゴール

reStructuredText の第一のゴールは Python docstring および他のドキュメントのドメインで使用するために、大掛かりな使い方も十分に強力でありながら読み易くてシンプルなマークアップ文法を定義することです。 reStructutedText のマークアップが意図する目的は二つあります:

  • プレーンテキストの中で構造の表現を可能にする、標準的な一連の規則を確立すること、そして

  • そのようなドキュメントを便利なデータフォーマットに変換することです。

reStructuredText の第二のゴールは Python のインラインドキュメントのための標準(人には好みがあるので、できればいくつかあるうちの一つ)として Pythonコミュニティに(Pythonlab や BDFL [1] によってもたらされるという方法で)受け入れられることです。

[1]

Python の創造者 または 慈悲深き独裁者" こと、Guide van Rossum のことです。

これは、第一のゴールを明確にするための、最も重要なものから始まる、明確な設計目標です。

  1. 読みやすいこと。マークアップされたテキストはマークアップ言語に関するいかなる予備知識を持たなくても読みやすいものでなければなりません。 処理された形式と同様に、そのままの形式でも読みやすくあるべきです。

  2. 控えめであること。使用されるマークアップは可能な限りシンプルであるべきです。マークアップ構造のシンプルさは、マークアップの使用頻度におおよそ比例しているべきです。もっとも一般的な構造は、自然かつ明示的なマークアップを持ち、もっともシンプルかつ控えめであるべきです。あまり一般的でない構造は、自然であったり明示的なマークアップもなく、独特であるべきです。

  3. 明白であること。マークアップのルールは解釈のために開放すべきではありません。 いかなる入力に対しても、唯ひとつの可能な出力があるべきです(エラー出力を含みます)。

  4. 予測できること。マークアップ構造は、処理中に予期しない出力を引き起こすべきではありません。回避策として、非マークアップの文脈でマークアップ構造を使用している場合に、意図しないマークアップ処理を防ぐ方法があるできです(例えば、マークアップシンタックスそのものを記述している場合)。

  5. 直感的であること。マークアップは執筆者にとってだけでなく読者にとっても明示的かつ容易であるように留意されるべきです。マークアップの構造はプレーンテキストのEメールメッセージ、ニュースグループへの投稿、そしてREADME.txt ファイルのようなテキストドキュメントなどの自然に存在する情報源からその手がかりを得るべきです。

  6. 簡単であること。どの普通のテキストエディタをつかっても簡単にマークアップができるべきです。

  7. スケーラブルであること。マークアップはテキストの長さに関係なく、適用され得るべきです。

  8. 強力であること。マークアップは適度にリッチで構造化されたドキュメントを提供するのに十分な構造を提供するべきです。

  9. 言語中立であること。マークアップは英語だけではなく、複数の自然言語に(同様に人工言語も)適用されるべきです。

  10. 拡張可能であること。マークアップは、より複雑な汎用のマークアップやカスタムマークアップを追加するためのシンプルなシンタックスとインターフェースを提供するべきです。

  11. 出力形式中立であること。マークアップは複数の出力フォーマットへと処理するために適し、なにか特定のフォーマットに対して偏ったりしません。

前述の設計目標は、シンタックスの受け入れ、または拒否もしくは複数の案の中からどれかを選択する際の基準として使われています。

reStructuredText のゴールは docstring の内容や docstring の長さなどのようなdocstring のセマンティクスを定義することでは、断じてありません。 これらの問題はマークアップのシンタックスとは直交しており、仕様の範疇を逸脱しています。

また StructuredTextSetext との互換性を維持することも、reStructuredText のゴールではありません。reStructuredText は臆面もなく、それらの偉大なアイデアを盗み、また偉大ではないアイデアを無視します。

著者の注釈:

私たちが解決しようとしている問題(もしくは、おそらく提案された解決策)の特質上、前述のゴールは已むを得ず衝突します。私は Python Doc-SIG メーリングリストや他の場所で長年に亘って蓄積されてきた叡智を抽出・蒸留して、首尾一貫し矛盾のないシンタックス規則のセットを考え出し、またそれらを測るために前述のゴールを考え出すことを試みました。

必然的に、私の特定の選択に同意しない人々が存在します。ある人はマークアップのより細かい制御を望み、他の人は逆を望みます。 ある人は非常に短い docstring を考えていますが、また他の人は文書全体のテキストについて考えています。この仕様は適度にシンプルな形で、適度にリッチなマークアップ構造のセットを提供するための努力であり、ほどよい人たちの適度に大きなグループを満足させべきなのです。

David Goodger (goodger@python.org), 2001-04-20

歴史

reStructuredTextの仕様は、 StructuredTextSetext に基づいています。StructuredText は Zope コーポレーション (旧 デジタルクリエーション)のJim Fulton によって開発され、1996年に初めてリリースされました。 現在では、オープンソースの "Z Object Publishing Environment" (ZOPE)の一部としてリリースされています。 Ian Feldman と Tony Sanders による初期の Setext の仕様はその類似性によってどちらも StructuredText に影響を与え、少なくともこのアプローチの正しさの 証拠となっています。

1999年の後半に、私は自分のプロジェクトの一つで Python モジュールのドキュメントを書く方法を探していた時に StructuredText を見つけました。 StructuredText の バージョン 1.1 は Daniel Larsson の pythondoc に含まれていました。pythondoc は私の仕事に使うことはできませんでしたが、StructuredText が私のニーズにほぼ理想的なものであることが分かりました。 私は Python Doc-SIG (ドキュメンテーションに特に関心のあるグループ)メーリングリストに参加し、StructuredText "標準" の欠点について進行中の議論を見つけました。この議論は、1996年にメーリングリストが開設された当初以来、ことによるとそれ以前から継続していました。

私は自身の拡張と Doc-SIG のメンバーから提案されたいくつかで、オリジナルのモジュールを修正することを決めました。私はすぐにモジュールを念頭に置いて書かれていないことに気づき、"re" 正規表現モジュール(このプロジェクトの名称の最初のインスピレーションです)に対応させることを含めて全体の手直しに着手しました。修正が完了した直後、StructuredText.py はZOPE ディストリビューションでは バージョン1.23 が最新であることに気づきました。バージョン 1.23 からの新しいシンタックス拡張を実装するのは、モジュールの複雑度が圧倒的になっていて、絶望的な課題であることが分かりました。

2000年、 StructuredTextNG ("次世代: Next Generation")がZope コーポレーション (旧デジタルクリエーション)で始まりました。 多くの改良点がありますが、それでも古い StructuredText の問題に苦しんでいます。

私は完全に書き直すときだと判断し、 reStructuredText SourceForge project(現在は非アクティブ)をスタートさせました。 私のモチベーション("かゆい"ところ。"引っ掻く"のが目的です)は、次のとおりです:

  • 私が書くプログラムのインラインドキュメントのための標準のフォーマットが必要。このインラインドキュメントは、HTMLのような他の便利なフォーマットに変換が可能なこと。他にも多くの人が同じことを望んでいると信じている。

  • 私は Setext/StructuredText のアイデアを信じている。そして正式に標準となる手助けをしたい。しかし、現在の仕様と実装には、死に物狂いの修正が必要な欠陥があると感じる。

  • reStructuredText はドキュメントの抽出と処理システムのための基板の一部を形成でき、Python に大きな恵みをもたらすことができる。しかしそれは一部のみではなくて全体である。reStructuredText はマークアップ言語の仕様であり、パーサのリファレンス実装だが、システムの全てになることを熱望はしていない。 私は過剰な野心によって reStructuredText や架空の Python ドキュメントプロセッサが死産になることを望んではいない。

  • なにより、私は多くのプログラマの不幸のタネ、ドキュメント書きの雑用を和らげる手助けをしたい。

残念ながら、私は異動し、このプロジェクトに関わらなくなってしまいました。 2000年11月、StructuredText の問題と現実的な解決策を列挙し、仕様の最初の草案を完成させるための時間を作りました。 この最初の草案は、3部構成で Doc-SIG に投稿されました:

2001年3月の Doc-SIG での活動の慌ただしさは、私に仕様をより改訂し、より洗練させることに拍車をかけ、その結果が今あなたが読んでいるものです。 reStructuredText プロジェクトの分派は、単一のマークアップスキーマでは考えぬかれた方法であるにも関わらず、十分ではないかも知れないという認識でした。Doc-SIG での終わりの見えない議論を鎮めるために、柔軟なDocstring 処理システムフレームワーク を構築することが望まれました。 このフレームワークは2つのプロジェクトの中で、より重要なものになりました; reStructuredText はより大きなフレームワークの中の一つのコンポーネントとしての地位を見つけたのです。

プロジェクトの web サイトと最初のプロジェクトのリリースは、Doc-SIG への仕様の二次草案 [2] および PEP 256、257 および 258 [3] の一次草案の投稿を含め、2001年6月にロールアウトしました。 これらのドキュメントとプロジェクトの実装は、急速なペースで進化していました。 実装の歴史の詳細は プロジェクト履歴ファイル で見ることができます。

2001年11月には reStructuredText のパーサは完成に近づいていました。パーサの開発は、小さな便利機能の追加、シンタックスの改善、抜け漏れの対応、そしてバグ修正を続けました。長い休みの後、2002年初頭には開発のほとんどが Docutils の他のコンポーネント "リーダ"、"ライタ" そして"トランスフォーム" に移りました。"スタンドアローン" リーダ(単一のテキストファイルを処理する)は2月に完成し、基本的な HTML ライタ(HTML4.01 を提供し、CSS-1 を使います)は3月上旬に完成しました。

PEP 287 "reStructuredText 標準 Docstring フォーマット" は、Python のdocstring、PEP、そしてその他のファイルの標準フォーマットとして、reStructuredText を正式に提案するために作成されました。これは最初2002年4月2日に、 comp.lang.pythonPython-dev メーリングリストに投稿されました。

reStrucuturedText のバージョン 0.4 および Docstring 処理システムプロジェクトは、2002年4月にリリースされました。2つのプロジェクトはすぐにマージされ、"Docutils" と名を改め、0.1 がまもなくリリースされました。

[2]

二次草案の仕様:

[3]

PEP の初期草案:

PEP の現在の作業バージョンは http://docutils.sourceforge.net/docs/peps/ で 見つけることが可能で、公式バージョンは PEP マスタリポジトリ で 見つけることができます。