README: Docutils 0.12

Author:David Goodger Contact:goodger@python.org Date:$Date: 2014-07-07 02:36:36 +0000 (Mon, 07 Jul 2014) $ Web site:http://docutils.sourceforge.net/ Copyright:

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

Contents

• README: Docutils 0.12
  • クイックスタート
  • 目的
  • リリース & スナップショット
  • 必要条件
    • Python_3 互換性
  • プロジェクトのファイルとディレクトリ
  • インストレーション
    • GNU/Linux, BSD, Unix, Mac OS X など
    • Windows
  • 使い方
  • ドキュメントの変換
  • テストスイートの実行
  • 助けを求めるには

クイックスタート

これは直ぐに始めたい & さっそく実行したい人のためのものです。

1. Docutils には以下のURLから入手出来る Python （バージョン 2.3 またはそれ以降）が必要です。

   http://www.pyhton.org/

   詳細については下記の 必要条件 を参照してください。

2. 最新の Docutils コードを使ってください。 Subversion リポジトリ またはスナップショットからコードを入手します:

   http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar

   詳細については下記の リリース & スナップショット を参照してください。

3. テンポラリのディレクトリ（直接 Python の site-packages ディレクトリに 入れないで ください）に TAR ボールを解凍し、アーカイブを展開してできた ディレクトリに移動し、管理者の権限で setup.py install を実行します。 ウィンドウシステムでは install.py をダブルクリックすれば十分でしょう。

   詳細については下記の インストレーション を参照してください。

4. reStructuredText ドキュメントを変換するにはフロントエンドスクリプトを使います。 次の例を試してください:

   rst2html.py FAQ.txt FAQ.html         (Unix)
   python tools/rst2html.py FAQ.txt FAQ.html  (Windows)
   

   詳細については下記の 使い方 を参照してください。

目的

Docutils プロジェクトの目的は、プレーンテキストのドキュメントをHTML、XML、そして LaTeX などのような便利な書式に加工するための道具のセットを作ることです。 以下のソースのサポートが実装されています:

• 単一ファイル

• PEP (Python 拡張提案)

以下のソースのサポートを予定しています:

• Python モジュールやパッケージから、名前空間の文脈に沿って抽出されたインラインドキュメント

• E メール（RFC-822 ヘッダ、クォートされた抜粋、署名、MIME パート）

• "ウィキリンク" のグローバル参照の探索と、ウィキ

• 複数の章のファイルを一冊の本に編んだような、複合ドキュメント

• そして、それ以外に見つけたもの

リリース & スナップショット

私たちは "早く & 頻繁にリリースする" というポリシーに従うように努めていますが、新しい機能はしょっちゅう追加されます。Subversion リポジトリの中のコードは通常、バグの無い状態なので、現時点でのスナップショット（通常はリポジトリに変更が コミットされてから１時間以内に更新されます）を使う事をオススメします:

• Docutils のコード、ドキュメント、フロントエンドツールおよびテストの スナップショット: http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar

• Sandbox （実験的なコードや、コントリビューションコード）のスナップショット: http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/sandbox/?view=tar

最新の動向を保つために、定期的にスナップショットの新しいコピーをダウンロードしたり、 Subversion リポジトリ の作業コピーを使ってください。

必要条件

コードを実行するには、 Python がインストールされていなければなりません。 Docutils は Python のバージョン 2.3 から 2.7 までと、バージョン 3.1 および3.2 （cf. Python_3 互換性 ）に互換性があります。

Docutils は、次のモジュールがインストールされていれば、機能性拡張のために それらを使います:

• Python Imaging ライブラリ または PIL は、画像操作のために使用します。

• Pygments シンタックスハイライターは、 code ディレクティブや ロールのコンテンツに使用します。

Python_3 互換性

Docutils のコードベースは Python_2 用に書かれており、 Python_3 への移植 は "オンデマンド" の翻訳を用いています。

• Python_3 でインストールをする際に、 setup.py スクリプトが Python_3 互換の ソースを build/ ディレクトリに生成し、 test3/ サブディレクトリ内で テストを実行します。

• tools サブディレクトリの中のスクリプトは、変換することなく、全ての サポートされている Python のバージョンで動作します。

• インストールせずにソースを変換（例えばテスト用）するためには、 python3 setup.py build を実行します。

• ソースを編集するとき、対象のファイルを Python_2 上で変更し、ビルドコマンドを 再度実行します。

Python_3.x で Docutils を使うにはテストがあまりされていないですし、まだいくつか 問題があるかも知れません。

プロジェクトのファイルとディレクトリ

• README.txt: 今あなたが読んでいるものです。

• COPYING.txt: パブリックドメインの貢献と非パブリックドメインなファイルの著作権表示（ほとんどがパブリックドメイン）です。

• FAQ.txt: よくある質問（とその回答も！）

• RELEASE-NOTES.txt: 最近のリリースでの主要な変更のサマリです。

• HISTORY.txt: 現在と、過去の全てのリリースにおける変更の詳細です。

• BUGS.txt: 既知のバグ、およびバグレポートの仕方です。

• THANKS.txt: コントリビューターの一覧です。

• setup.py: インストレーションスクリプトです。次の "インストレーション" を見てください

• install.py: クイック & ダーティなインストレーションスクリプトです。ただ実行するだけです。何かしらのカスタマイズやヘルプには、setup.py を使う必要があります。

• docutils: Python パッケージとしてインストールされる、プロジェクトのソースディレクトリです。

• docs: プロジェクトドキュメントのディレクトリです。概要は docs/index.txt を読んでください。

• docs/user: プロジェクトユーザドキュメントのディレクトリです。とりわけ、次のドキュメントが含まれています:

  • docs/user/tools.txt: Docutils フロントエンドツール

  • docs/user/latex.txt: Docutils LaTeX ライタ

  • docs/user/rst/quickstart.txt: reStructuredText 入門

  • docs/user/rst/quickref.html: 早わかり reStructuredText（HTML のみ）

• docs/ref: プロジェクトリファレンスのディレクトリです。docs/ref/rst/restructuredtext.txt は reStructuredText のリファレンスです。

• licenses: ディレクトリには非パブリックドメインのファイルのためのライセンスファイルのコピーが含まれています。

• tools: Docutils フロントエンドツールのためのディレクトリです。ドキュメントは docs/user/tools.txt を参照してください。

• test: ユニットテストです。ソフトウェアを使うためには必要ないですが、変更を行うつもりであれば非常に便利です。下記の テストスイートの実行 を参照してください。

Python_3 でインストールする時に生成されるディレクトリ:

• build: 変換されたソースです。

• test3: 変換されたテストです。

インストレーション

最初の一歩は .tgz アーカイブを一時ディレクトリ（Python の site-packagesディレクトリに直接 入れない でください）の中に展開することです。 アーカイブには distutils のセットアップファイル "setup.py" を含んでいます。 OS 別のインストレーション手順に続きます。

GNU/Linux, BSD, Unix, Mac OS X など

1. シェルを開きます。

2. アーカイブを展開してできたディレクトリに移動します

   cd <archive_directory_path>
   

3. パッケージをインストールします（このステップを完了するにはルート権限が必要かも知れません）

   su
   (enter admin password)
   python setup.py install
   

   もし python 実行形式が path にない場合、 /usr/local/bin/python のように完全なパスを指定しなければなりません。

   特定の Python バージョン用にインストールするには、セットアップの呼び出しでこのバージョンを使います。例えば

   python3.1 setup.py install
   

   異なる Python のバージョン用にインストールするには、必要なすべてのバージョンで手順３を繰り返します。最後にインストールしたバージョンがrst2\*.py ラッパースクリプトの シェバン行 に使用されます。

Windows

install.py をダブルクリックするだけです。もしこれが動かなかったら、次を試してください :

1. DOS ボックス（コマンドシェル、MS-DOSプロンプト、もしくはこの頃それらが呼ばれている名前の何か）を開きます。

2. アーカイブを展開してできたディレクトリに移動します

   cd <archive_directory_path>
   

3. パッケージをインストールします

   <path_to_python.exe>\python setup.py install
   

   特定の Python バージョン用にインストールするには、このバージョンのPython 実行形式を指定します。

   異なる Python のバージョン用にインストールするには、必要なすべてのバージョンで手順３を繰り返します。

オプションの手順:

• テストスイートの実行

• ドキュメントの変換

使い方

解凍した "tools" サブディレクトリにはたくさんのフロントエンドツールがあります。 Unix 環境でのインストレーションでは PATH 上にコピーを配置します。 "rst2html.py" フロントエンドツールから始めたいと思うでしょう。 ほとんどのツールは source path と destination path の２つの引数に、デフォルトで STDIN と STDOUT を取ります。オプションや引数の詳細についてはフロントエンドツールの "--help" オプションを使ってください。 すべてのドキュメントは Docutils フロントエンドツール（ docs/user/tools.txt ）を参照してください。

パッケージモジュールは継続的に成長し、進化しています。docutils.statemachine モジュールは独立して使用可能で、大規模なインラインの ドキュメントを含んでいます（もちろん reStructuredText のフォーマットで）。

貢献は歓迎します！

ドキュメントの変換

Docutils パッケージを展開、インストールした後、次のシェルコマンドによって含まれているすべてのドキュメントの HTML が生成されます

cd <archive_directory_path>/tools
./buildhtml.py ../

Windows システムでは、次のとおりにタイプします

cd <archive_directory_path>\tools
python buildhtml.py ..

<archive_directory_path> の最終的なディレクトリ名は、スナップショットの場合は "docutils" です。 公式リリースでは、ディレクトリは "docutils-X.Y.Z" となり、 "X.Y.Z" にはリリースバージョンが入ります。 別のやり方

cd <archive_directory_path>
tools/buildhtml.py --config=tools/docutils.conf          (Unix)
python tools\buildhtml.py --config=tools\docutils.conf   (Windows)

いくつかのファイルはシステムメッセージ（警告やエラー）を出すかも知れません。 docs/user/rst/demo.txt ファイル（アーカイブディレクトリ配下）は、意図的なエラーを５つ含んでいます（これらはエラー報告メカニズムをテストしています！）

テストスイートの実行

テストスイートは Docutils テスティング （docs/dev/testing.txt）に 書かれています。

テストスイート全体を実行するには、シェルを開いて次のコマンドを使います

cd <archive_directory_path>/test
./alltests.py

Windows では次のようにタイプします

cd <archive_directory_path>\test
python alltests.py

Python_3 でのテストには変換されたテストスイートを使います

cd <archive_directory_path>/test3
python3 alltests.py

長い区切り線、一つずつのテスト、そしてこのようなサマリが表示されるはずです

Ran 1111 tests in 24.653s

OK
Elapsed time: 26.189 seconds

テストの件数は時間とともに増えるでしょうし、報告される時間はテストを実行している計算機に依存するでしょう。 二つの時間の差は、テストのセットアップに掛かる時間を表しています（モジュールのインポート、データ構造の作成、等）。

いずれかのテストが失敗した場合は、 バグレポートを開き 、 メールを送る か、もしくは web インターフェース 経由でメッセージをポストしてください（ Bugs を参照してください）。 関連する出力、あなたのオペレーティングシステムに関する情報、Python バージョン、Docutils のバージョンをすべて含めてください。Docutils のバージョンを確認するためには、 rst2* フロントエンドのどれか、または tools/quicktest.py を--version オプションを付けて使います。例えば

cd ../tools
./quicktest.py --version

Windows ユーザは次のコマンドをタイプします

cd ..\tools
python quicktest.py --version

助けを求めるには

Docutils や reStrcuturedText についての質問があったり、支援が必要な場合は、Docutils ユーザーズ メーリングリストにメッセージを送ってください。