¶
Docutils のマークアップ文法とパーサコンポーネント¶
| Date: | $Date: 2010-09-01 16:08:50 +0000 (Wed, 01 Sep 2010) $ |
|---|
注釈
"reStructuredText" は １語 です、 ２つではありません！
Contents
reStructuredText は読み易く、見たままが得られるプレーンテキストの マークアップ文法とパーサの仕組みです。インラインの（Python の docstring のような）プログラムドキュメントや、シンプルな Web ページや個別の ドキュメントを簡単に作成するのに便利です。 reStructuredText は特定のアプリケーションドメインのための拡張として 設計されています。reStructuredText のパーサは Docutils のコンポーネントです。 reStructuredText は StructuredText や Setext 軽量マークアップシステムの 改訂であり、再解釈なのです。
reStructuredText の第一のゴールは、Python docstring およびその他の ドキュメントのドメインで使用するために、大掛かりな使い方も十分に強力でありながら、読み易くてシンプルなマークアップ文法を定義して実装することです。 マークアップが意図する目的は、reStructuredText ドキュメントを、使いやすい、 構造化されたデータフォーマットに変換することです。
全て reStructuredText を使ってドキュメントが書かれた Python モジュールの 例として statemachine.py を参照してください。
ユーザ ドキュメント¶
ReStructuredText 入門書 （HTML ファイル、又は テキストソース ）。
早わかり reStructuredText （ユーザリファレンス）
reStructuredText チートシート （テキストのみ; 1 ページは文法、 1ページはディレクティブとロールのリファレンス）
質問または Docutils や reStructuredText の助けが必要なユーザは、 Docutils-users メーリングリストに投稿しましょう。
リファレンス ドキュメント¶
reStructuredText 入門 （reStructuredText の ゴール と 歴史 を含む）
オンラインで挑戦¶
Docutils をダウンロードせずに reStructuredText を試してみたいなら、 reStructuredText オンラインレンダラー が使えます 。 設定してくれた Jiri Barton に感謝します！
喜びの声¶
次の反響はメーリングリストや comp.lang.python ニュースグループへの 未承諾のポストからの抜粋です。抜粋なので、しばしば文脈が失われたり、 時にはメッセージがトーンダウンしています。
Ueli Schlaepfer on Doc-SIG, 2002-03-28:
僕はラボの（主に matlab環境の）仕事をやりながらノートを作成するためのツールとして reST を選択した。それ以来、それらのドキュメントの品質は主に次の二つの理由から著しく向上したよ:
僕はもはや他のツールに切り換える必要がなくなり、ドキュメントを書くことへの敷居がとても低くなったんだ。 "他のツール" というのは WinWord のことね…
その上僕は、自分が考え得る他のどのツールよりも簡単にこれらのドキュメントを作れる強力なマークアップ構造のセットを手にしている。
自分の Python コードからドキュメントを抽出するために、同じツールを適用してすぐに仕事を進めることが出来るから、 reST/DPS [今は Docutils だね] には感謝してるよ。なあ、それの印刷やブラウズ可能なバージョンが 無料 なんだぜ！ 個人的に、このことは大きな利益だと思っているんだ。
... 毎日使う重要な構成要素、そして必要であればさらに多くのものが全てそこにあるんだ。 ...
いい PEP だ、David！ 次のステップは何？ このコードは標準ライブラリに 組み込まれるべきかな？ 我々は標準ライブラリのドキュメントを reStructuredText に変換するべきかな？
Timothy Delaney on comp.lang.python, 2002-04-03:
自分は reStructuredText のドキュメントをすべて読んでテキスト版とHTML版を比較してみた。テキスト版は何か "特別" だったときに、ほとんどの場合にそれを明示的に作るんだけど、 非常に 読み易いということが分かったよ。
特にハイパーリンクを行う仕組みが特に気に入った。
自分からは間違いなく +1... 自分は本当に標準の、きれいな docstring 用フォーマットにしたいよ。 自分の次の Python のプロジェクトが簡単に終わらせられるかも知れないな...
Guido van Rossum on Python-Dev, 2002-04-03:
reStructuredText は docstring をマークアップするのにいい形式だと思う; おそらく与えられた条件に見合う（かなり手の込んだことができる機能セットにも関わらず、"生で" HTML よりも読みやすい）。
Richard Jones on comp.lang.python, 2002-04-03:
私にはマークアップと非マークアップの中間のように見えるね。 マークアップの機構を持っているから、それを目一杯使うことができる。 もしくはいくつかのシンプルな規則（マークアップの中で最も基本的な形式）に従えば、もっと細かい瑣末なことを気にする必要はない。 マークアップであるにも関わらず、
@section{The Section Title}と
The Section Title -----------------の後者の方はマークアップに 見えない という違いは明白だよ。
Guido van Rossum on Python-Dev, 2002-04-04:
Structured text はある状況においては本当に良いアイデアだ; reST はこれまでみたどのバージョンよりもずっといいアイデアの実装だよ。
Max M on comp.lang.python, 2002-04-05:
どんなプログラマも 15 分かそこいらで基本的なことは覚えられるね。
それにドキュメントを書くのがとてもとっても簡単だ。私がもしも 本を書くようなことが（再び）あるとしたら、ReST で書くと確信するよ。
あと仕様から言える限りにおいて、ReST は僕が Structured text で 抱えていた問題のほとんどを解決できる。いくつかはちょっと複雑になるし、 いくつかはもっとシンプルになるだろう。どれもこれも、いい掘り出し物だ。
確実に使うことになるだろうね。僕も Zope 統合されることを願っているよ。
David Abrahams on Python-Dev, 2002-04-06:
ところで、僕は reST にとても興奮しているんだ。C++ のコメント用に イケてるマークアップ記法を探していて、reST はその条件にピッタリ かも知れない。
Eric Jones on Python-Dev, 2002-08-01:
reStructuredText か、もしくはそのマイナーバリエーションのどれかがごく近いうちに docstring の"標準" になっていくのを見てみたいね。私は長いこと、所定のフォーマット と 関連処理のツールスイートが標準ライブラリに含まれていないことを嘆いている。 フォーマットが完璧じゃなくても（私には非常に良さそうみ見える）、そろそろ道理に合った候補を選んで先に進む時だよ。
これはインターネットであり、reStructuredText のアイデアに対してときに猛烈に、反対する人々がいました。 これらの 宝石たちを発見することは、読者の練習問題として残されています。