ドキュメント自動生成計画¶
仕事のプロジェクトで、慢性的に人手が足りていません。そこで、ドキュメントは出来るだけ自動生成にしようと画策しています。
今のところ、 doxygen と CUnit を使用して以下のドキュメントが自動生成されています。
APIリファレンス
単体テスト項目書
単体テスト成績書
会社のモノを勝手に公開するわけにはいかないので、残念ながら成果物を掲載することは出来ないのですが、生成手順についてメモしておきます。
APIリファレンス¶
doxygen_ → html → HTML Help
htmlからWindowsのHTMLHelp形式にするためには、MicrosoftのサイトからHTML Help Workshopをダウンロードしてインストールしておく必要があります。あとはdoxyfileにGENERATE_HTMLHELP = YES と記述して、関連する項目(コンパイラのパス等)を設定するだけで、doxygenが自動的に生成してくれます。
ただし、あまり見やすいヘルプは作ってくれません。自分は、@mainpage と @defgroup を使って、提供機能からAPIを引けるように工夫してみました。
単体テスト項目書¶
doxygen_ → XML → 自作XSLTと結合して HTML
GENERATE_XML = YES とすることで、 doxygen はXMLを出力してくれます。そこで、XMLに自作のXSLTを結合させて、自動生成のHTML(HTMLHelp)よりも見やすく作ってみました。XMLとXSLTの結合には Apache XML project の xt を使用しました。
xt導入 には若干手間取りましたが、googleで見つけたサイトで手順が書かれていたので、すんなりと導入することが出来ました。‥‥が、IE6.0の出力結果と微妙に違うようです。
実はHTMLに変換した理由は別にあって、WordでHTMLを読み込ませて、Wordファイルとして提出するためだったりします。別にWordじゃなくても‥‥とか思うんですけどねぇ。
単体テスト成績書¶
CUnit_ → XML → 自作XSLTと結合して HTML
CUnit もXMLを出力することが出来るので、これもXSLTを用意しました。項目書と成績書の両方ともXMLなのだから、もう一工夫すれば項目書にテスト結果も載せることが出来ると思います。今回は時間が無いので、これは次回の課題としておきます(^^;
今後の自動生成¶
次は、後日メンテ用の内部設計書ですかね。あと、コマンド一発で
VSSからソース取得
VC++でコンパイル
テスト実行
ドキュメント生成(doxygen,xt)
ドキュメントアップロード
とかやってみたいですね。
