wiki:using_rest_in_tracwiki

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を使うには二つのステップがあります:

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

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

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

wikiのプリフォーマット記法はご存知ですか?あの波括弧が三つ並ぶ気持悪いやつ です.プリフォーマット記法の中身を "#!rst" で始めると,ReST記法で文章を書け ます.詳しい記法は http://omake.accense.com/wiki/WikiRestructuredTexthttp://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!