Wiki ナビゲーション

TracからReSTを使う

ReST(reStructuredText)について

ReST(reStructuredText)とは，プレーンテキスト形式での直観的な読みやすさと， HTMLやXMLに一意に変換可能なマークアップ記法としての機能の両立を目指したテキスト記法です．簡単にいうと，「 そのまま読んでも読みやすく，HTML形式などの他の形式にきれいに変換できるテキストの書き方 」です．ReSTはStructuredText と呼ばれるインデント指向の記法の無駄な構造を見直した記法で，よりメンテナンスしやすく，学習コストの低い記法を目指しています．ReSTドキュメントの仕様や他の形式に変換するためのツールであるdocutilsはPythonコミュニティで生まれたものですし，Pythonモジュールの中にもReSTで書かれたドキュメントを提供しているものがいくつかあります．しかしながら，その簡潔性と表現性の優れたバランスから，Python関連のプロジェクトに限らず，幅広いソフトウェアプロジェクトで採用されつつあります．

ReSTの構文を学びたければ，まずは以下の日本語のサイトが参考になるでしょう:

TracとReSTを組み合わせよう

さて，Tracのwikiシステムは，ご存知の通りあの特有のwiki記法を使っています．正直，私はwikiは苦手です．なぜかって？こぎたないCamelCaseのページリンクや，階層構造をいじるたびにちまちまと数合わせせねばならないインデントのことを考えると気が重くなって，何も書く気がしなくなるんです．それに比べて，ReSTの美しさ！ Tracを3日真面目につかってみて，私は考えました．「もしかして，TracでReST使えちゃったりしないかな？」ビンゴ！ありました．これでみんな幸せになれます．さあ，あなたもいますぐReSTで整然としたドキュメンテーションライフを送りましょう．

TracからReSTを使うには二つのステップがあります:

ReST記法マークアップをWiki記法の中で使う
ReSTマクロプラグインを使う

1. Wiki記法中でReST記法マークアップを使う

Tracを動かしているPythonのsite-packagesの中にdocutilsがある場合，Trac wiki の中でReST記法を使えます．

wikiのプリフォーマット記法はご存知ですか？あの波括弧が三つ並ぶ気持悪いやつです．プリフォーマット記法の中身を "#!rst" で始めると，ReST記法で文章を書けます．詳しい記法は http://omake.accense.com/wiki/WikiRestructuredText や http://omake.accense.com/wiki/WikiRestructuredTextLinks を参照してください．

注目して欲しいのは，ReSTでも，Trac wiki特有のチェンジセットやチケットを参照できることです．wikiだとこうなりますよね:

#42          ... 42 番のチケット
[5963]       ... チェンジセット 5963

ReSTだとこうなります:

:trac:`#42`          ... 42 番のチケット
:trac:`[5963]`       ... チェンジセット 5963

タイプ数が多いって？そんなこと気にしちゃいけません．まさか，チケット番号ばかり100個も並んだ文章を書くようなバカな真似しないでしょ？

もちろん，まだwikiに未練があるのなら，wiki記法と組み合わせて使ったっていいんですよ！

2. ReSTマクロプラグインを使う

もう一つの方法，そしてドキュメントをメンテナンスしている人に強く勧めたいのがこの方法です．TracにReST macroというプラグインを追加すると，レポジトリの中にあるドキュメントを読み出して，wikiのページに表示してくれるんです．

使い方は(どっちかというと)簡単．

まず，作者のPhilippe Normandに感謝しつつ ReSTMacro のページに書かれているリポジトリからソースコードをチェックアウトします．

次に，ソースコード中のsetup.pyがあるディレクトリに移動して:

python setup.py bdist_egg

を実行します．注意して欲しいのは，ここで使うpythonはtracの使っているpython と同じ(バージョン)にせねばならないということです．

eggファイルができたら，それをTracのプロジェクトディレクトリ下にあるplugins ディレクトリにコピーしてください．さらに，Tracのプロジェクトディレクトリ直下に rst_cache という名前のディレクトリを作成して，Webサーバのユーザが読み書き可能になるように権限を設定します．

これだけで，ReSTMacroを使えるようになります．リポジトリにReSTで書かれたドキュメントをcommitしたら，適当なwikiページの中で:

[[ReST(/repos_root/your/rest/file.txt)]]

のように記述してください．リポジトリ中の /repos_root/your/rest/file.txt の内容がレンダリングされて表示されるはずです．ReSTMacroの中でも，基本的な ReST 記法や Tracリンクを使えます．

トラブルシューティング

trac.ini のdefault_chasetのデフォルト値はiso-8859-1です．このままだと，日本語のドキュメントが文字化けします．utf-8に設定しましょう．
複数の trac の tracenv/plugins に同じReSTプラグインが入っていて、一つのインタプリタでサービスを提供しようとすると、プラグインモジュールを違う名前のパスから多重ロードしようとして、「ReSTマクロはありません」というエラーが出ます。この問題を避けるには、プラグインを共有のプラグイン置き場 (/usr/local/share/trac/plugin など) に配置して、 tracenv/conf/trac.ini に以下のセクションを追加して明示的にロードしてください:
```
[components]
tracrst.macros.* = enabled
```

Enjoy!

異なるフォーマットでダウンロード:

Plain Text