Sphinxを使ってみた

仕事でちょっとした学生実験以上・学士論文未満程度のリサーチをやっていて、文書にまとめる機会があったので、前からちょっと気になっていたSphinxを使ってみました。Sphinxというのは、reStructedTextという形式で書かれたテキストファイルを、HTMLを始めとした複数の形式に変換できるというもの。実行にはPythonが必要です。

404 Not Found
reStructuredText

なんだかよくわからなくても上記Sphinx-Users.jpの「Sphinxをはじめよう」に従うだけで大丈夫です。例えばカレーの作り方のドキュメントを作るとして、

カレーの作り方
================

今明かされるMass Kaneko式カレーのレシピ!

.. image:: curry.jpg

材料
----------------

* とりにく
* かぼちゃ
* にんじん
* モロヘイヤ
* カシミールカレーパウダー
* ココナッツミルク
* ナンプラー

作ってみよう
----------------

まずはとりにくに塩をすりこみます。 **入れすぎに注意!**

みたいにテキストファイルを書いて、

$ make html

とすると、書いたテキストの内容が見栄えのいいHTMLになる…という具合です。どんな見た目かは 404 Not Found が参考になるでしょう。

SphinxPythonというソフトウェア開発の世界で生まれたものですが、「階層構造の、ある程度大きい、ハイパーリンクのあるドキュメント」という場合にはうってつけで、ソフトウェア開発に限らず、ドキュメントを書く分野では使えますね。

また、reStructedTextはテキストファイルです。単なるテキストとしても文書構造がわかります。つまり…Subversionなどのバージョン管理システムで差分管理がやりやすい。変更前後で何が変わったのか、誰が変えたのかを簡単に管理することができます。(カレーの例で言えば、誰かがうっかりナンプラーをおたふくソースに書き換えてしまっても、すぐにわかります。)

今私が仕事で書いているレポートにも向いていそうです。しばらく使ってみることにします。