sphinx + blockdiagがとっても最強すぎる件

Yokohama.pmで @tk0miya さんが発表していた sphinx + blockdiag。

sphinxはテキストファイルをWiki記法みたいな書き方で書いてmakeするだけでhtmlとかpdfを生成してくれる魔法のツール。pythonで書かれてる。

blockdiagはテキストファイルから遷移図とかシーケンス図とかネットワーク図とかを生成できるツールで、sphinxのreSTファイル内に埋め込むことができる。

コードに対するドキュメントなどはコードに埋め込んじゃえばいいんだけど(pod,javadoc、いろいろあるよね)、設計に関するドキュメントだとか運用に関するドキュメントは別に書かないといけなくて、ついつい後回しにして、必要になった時には後の祭り…なんてことが結構ある。かと言って、開発初期とプロダクトが成熟してきたときでは仕様に結構な差があったりして、初期に書いたドキュメントの図とかをメンテナンスするたびに(photoshop|cacoo|keynote|powerpoint)をたち上げてちまちまと図を修正して…「もう嫌だ！」ってなることも多い。

でも、sphinx + blockdiagでは、編集の必要があるのがテキストファイルだけだし、普段コード書いてるテキストエディタからシームレスにドキュメントのメンテもできるので、仕様が変わったり設計が変わったり運用のアレが変わったりしたときに、すぐに対応することができる。開発をする際にも、コミットの粒度を小さく保つといろいろと幸せになれるけど、これはドキュメントにも同じことが言えて、sphinx + blockdiagだとドキュメントもとてもLightWeightに書けるので、ドキュメントへのコミットの粒度も小さく保つことが簡単にできることになる。

sphinx + blockdiagでドキュメントを書き始めてから結構しあわせなので、みなさんも使うといいと思います。