ドキュメント生成にSphinxを用いる

色々と思う事があって、最近はドキュメントをきちんと書こうという気持ちになっているのですが、最初に書き始めるまでに膨大な時間がかかってしまいます。ソースコードを書き始めるのは心理的な抵抗が無いのにも関わらず、ドキュメントを書き始めるのに時間がかかってしまうのは何故なんでしょうか？

そんな事を考えていてウェブを調べてみると、ちょっと良さそうなドキュメント生成ツールを見つけました。なんだか有名なツールのようですが、私が知ったのはつい最近。

http://www.sphinx-doc.org/en/stable/

何やら独自のマークアップ言語で記述すればhtmlやlatexやepubやなんだかんだに変換が出来るという・・・一見するとよく見る類のものに見えます。そして、いつものように試してガッカリするんだろうなと期待せずにチュートリアル的な内容をこなしてビックリ。なかなか綺麗な出力が得られることがわかりました。

例えば、sphinx-quickstartで作ったプロジェクトのファイルに日本語を入力してUTF-8で保存し、make latexpdfjaした時の出力が以下。

もちろんSphinx自体のサイトもSphinxで作られていて、これがなかなか綺麗な仕上がりです。
http://www.sphinx-doc.org/en/stable/contents.html

ソースコードの類を書く人にとって、WordのようなWYSIWYGはやはり辛いんでしょうか。よく考えてみるとソースコードの整形だってエディタやツールにやらせています。よほどの事情(とにかく気分転換したいので単純作業とかしたい・・・とか?)が無い限り、手で一文字一文字整形する人は稀でしょう。このノリで考えると、文章を整形しながら書くというのは、ソースコードを書く人の感覚と少し異なるのかもしれません。「整形は後で」って思っていても、そもそもソースコードを書く人は綺麗好きな人が多いので、やっぱり整形作業も始めちゃうというジレンマがあるのかも。

という事で、ひとまず道具を開拓してみただけなのですが、実際に説明不足のプロジェクトが山のようにあるので、何かのプロジェクトで使ってみたいと（今は）考えています。