主に作業メモ。ソフトウェア開発プロジェクトでは多かれ少なかれ様々なドキュメントを作成する。一般的にはMicrosoft OfficeなどのOAソフト(つまりWordやExcel)で文書を作成するのだけれども、これが非常に管理し難い。本当はWikiなどで管理するのがいいのだけれども、「納品」とか「持ち出し」を考えたときに、Wikiサーバを立てるのはあまりうまくない。というわけで以前に少しだけチェックしていたドキュメント作成ツールについて改めて調べてみた。
Sphinx
Python製のドキュメント生成ツールである。reStructuredText記法という文法で記述したテキストツールをCUIでコンパイルすると、HTMLやPDFなどの各種ドキュメントを生成してくれる。
ReVIEW
結論としてはSphinxでほぼ決まりなのだけれども、どうにもreStructuredText記法には違和感が消えなかったので、Ruby製のドキュメント生成ツールであるReVIEWも調べてみた。
- インストールはWindowsだとSphinxに比べてハードルは若干高め。CygwinとRubyを導入した上でインストールする必要あり。そしてトラップがある(後述)
- ReVIEW記法は、Wiki記法に近いので非常にしっくりくる。記法としてはベストだと思った。
- ドキュメントは少ない、というかソフトウェア名称がSEO的に微妙で検索しにくい
- ドキュメント作成ツールの検討(Sphinx、ReVIEWとか) - wadahiroの日記
- kmuto ReVIEW で検索するといいらしい
- 基本的にPDFやEPUBを出力するためのソフトウェアであり、現時点ではHTMLの出力は限定的にしかサポートされていない模様。
というわけで、使えるか使えないかという視点でみると、残念ながら適用するのは難しそうだった。
Sphinxで設計書を書いてみる
Sphinxで設計ドキュメント類を書くことについては、冒頭でも紹介した以下の情報がある。
ただ、このテンプレートだと何というか「作成のプロセス」がうまくイメージできなかった。というわけで、素直に手元の環境で簡単なサンプルを書いてみることにしてみた。しばらく実験的に更新してみたい。githubで公開しているので興味があれば確認いただきたい。
- 実際に書いてみるとわかることも多い。プロジェクトで実際に運用するまえにいろいろと試行錯誤しておかないとうまく適用できない予感。
- いろいろと便利な機能(ディレクティブ)があるけれども、これをどのように取捨選択するのかが難しい。
- 以下、これから試してみたいこと(いつかやる)
参考
- http://wadahiro.hatenablog.com/entry/20120502/13359444it11
- ひととおり調べた段階で発見したブログエントリ。結論はほぼ同じだった……
おまけ
上記の検討をしている中で、そういえばWordPressも静的HTMLを吐けるのだから、これで設計書管理するという手もあるなぁと一瞬考えてみたけれども、怖くなったので考えるのはやめた・・・