Docutils と Ruby で快適ドキュメント生活
まったく新しいネタではないですが、以前作ったものを整理するためにadvent calendarに参加します。
0. reSTが好きです
まず私は setext ( structured text ) が好きでした。したがって当然のように reST が好きです。細かいことを言わなければほとんどの場合は Markdown でまかなえたりするのですが、Office ファイルにして印刷用に調整を入れる場合は reST を使っています。
reST なので当然
- Python
- docutils
を使います。インストール方法は端折ります。簡単です。
1. rst2html.py + guard でとにかく書く
まず最初の段階は「手早くプレビューを回す」です。
そこで reST と同じかそれ以上に好きな Ruby のツールである guard を使います。これはファイルの変更を監視して様々な処理を行うためのライブラリで、ここでは
- guard-shell から rst2html.py を叩いて HTML を生成
- できた HTML をブラウザで開いてプレビューするが、HTML の生成を監視して guard-livereload で自動 reload
の二つの仕事を担ってもらいます。実際に利用するライブラリは以下の3つです。
Web サーバは適当に Python の SimpleHTTPServer や Ruby の WEBrick などを使います。
- 以下のような Gemfile, Guard を用意
- guard を起動
- 内容はなんでもいいので HTML を生成して、livereload で capture
- あとはひたすら .rst ファイルを編集しまくるだけ
です。
reST-writing environment with realtime HTML-preview — Gist
2. rst2odt.py + rake で odt を生成して仕上げ
プレビューで内容に問題がなければ今度は拙作の
を利用します。これを git clone して対象の rst ファイルを sample.rst に rename して置いておきます。こいつのできることは
- rst2odt.py を叩いて reST から odt ファイルを生成
- odt ファイル生成時に利用する stylesheet をコンパイル
- stylesheet の調整を自分で XML で行うこともできる
- open コマンドでできあがった odt ファイルを開く
です。残念ながら reST ファイル、odt ファイルとも sample という名前に決め打ちのまま早2年放置となっていますし、open はこれを抽象化するライブラリを利用した方がいいだろうなと思いつつ自分は Mac しか使っていないのでそのままです。
odt ファイルを開いたらあとは印刷用にスタイルの調整をしつつ、この段階で間違いに気づいたら rst ファイルの修正を行い、その都度
rake open
するという流れになります。
最後は LibreOffice ( OpenOffice.org ) から PDF エクスポートすると共有しやすいと思います。
3. まとめ
あまり統一感はないですし、拙作の rst2odt_stylesheet rake タスクの完成度が低くてアレですが、少なくとも Word でいきなり文章書くよりははるかに楽にドキュメントが書けると思います。
reST は前身の setext の特徴の一つである「メールにそのまま埋め込んでも不自然でない」を体現しつつ table の記法も整理されているので、とても応用範囲の広い記法です。またこの方法で odt に変換したのちに PDF に export すると、最終的にできあがった PDF にも文章構造が反映されるので、長いドキュメントでもそれなりに読みやすくなるのもメリットの一つです。
猫も杓子も Markdown の昨今ですが、ぜひ reST でドキュメントを書いてみてはいかがでしょうか。
惜しいのは Markdown のように処理系が各言語で出そろっていないところでしょうか。実質 Python 専用なので Trac で利用することはできても Redmine から利用するのは難しいと思います。誰か移植しないかなー(ﾁﾗｯﾁﾗｯ