doxygenで、各種形式のドキュメントを作ってしまおう
世の中のプログラマは、基本的にものぐさだ。
(あ〜、言っておくが、カット＆コピーしまくるのは、ものぐさとは言わない。ありゃ、ロボットだと思う)
コード作りには熱心になれても、ドキュメント作成になると一気に能率が落ちるのが常だ。
てな訳で、ソースコードからドキュメントを自動生成しようとする人達が現れる。自分の狭い知識では、
あたりが有名みたいだ。
で、題名にあるpythonで、(pydocがあるのに)何故わざわざdoxygenを使うのかって言うと、引数とか返値などを明示する書き方とか、それをドキュメント化する手段がないかな？と探した結果が コレ という訳。後、doxygenだと後で述べるように、様々な形式のドキュメントファイルを一気に出力できる所があるので。
引数とか返値とか何で細かく書きたいのか？って言うと、まぁ C/C++ に普段慣れているせいか、入出力の挙動を一定の書式で記述したいと思ったので。
(引数に特定のオブジェクトとか範囲値を受け取りたいと思って、assert やコメントを書くんだけどね)
docutilとかreStructuredTextとか探したんだけど、どうも そういった記述形式が見当たらなかったのよ。…どっかにあるのかな？
で、まぁ、doxygenにpythonコードを喰わせましょうと。意味合い的には、ドキュメント化の補助手段ですな。
能書きは ここまでにして、早速 試してみよう。
- Doxygen
http://www.stack.nl/~dimitri/doxygen/index.html
から、"doxygen-1.4.5-setup.exe" - Graphviz
http://www.graphviz.org/About.php
から、"graphviz-2.6.exe"
以上をダウンロード。
Graphvizは、特に必要じゃないけど、クラス関係を図化してくれるので入れちゃう。どちらも簡単セットアップできちゃう。
(Graphvizは、以前 しょぼいインストーラだったと思ったんだけど、今回試したら かなり良さげ)
ドキュメント化のサンプルとして、PythonMatrix:ElementTreeモジュールについてで紹介されている、ElementTreeを使ってみる事にした。
1.ElementTreeのコード展開
ElementTreeのコードを展開する。
$ tar xzvf elementtree-1.2.6-20050316.tar.tar ... $ tree elementtree-1.2.6-20050316 F:\WACKY\TEST\PYTHON\ELEMENTTREE-1.2.6-20050316 ├─docs ├─elementtree └─samples
コード本体は、elementtreeにあるので、こいつをdoxygenに喰わせる事にする。
2.doxygenを起動する
exe版のdoxygenを入れると、フロントエンドが付いてくる。
こいつを起動する。
コンソールから弄ってもOKなんだけど、初めての人には、何のこっちゃかわかんないので、お奨めしない。
ちなみに、コンソールからだと、↓概ね、こんな感じで進める。
$ doxygen -g hoge.cfg <= hoge.cfgという設定ファイルを出力させる。 $ vi hoge.cfg <= hoge.cfgをエディタで開いて、doxygenに読み取らせるファイルや出力形式の設定を行う。 $ doxygen hoge.cfg <= hoge.cfgで設定した内容に従って、doxygenにドキュメント化作業をさせる。
3.設定を行う
フロントエンドから、上側の「Wizard」ボタンを押す。
各タブに対して、様々な設定をかける。
まぁ、Visual Studioとかで、プロジェクトの設定かけるじゃん？あれみたいなもの。
以下では自分が設定した内容についてコメント入れているが、英語が全くダメーな人なので、多分うそ一杯。
なので、そこんとこ 鑑みてちょーだい。
Projectタブは、基本的な設定。
ここでは、以下のようにしてみた。
| Project name | タイトル名みたいなもの。ここでは、"ElementTree(doxygen)"とした |
| Source code directory | doxygenに喰わせるソースの在り処を示す。 サブディレクトリにもある場合、"Scan recursively"にチェックを入れれば良いと思う |
| Destination directory | doxygenに喰わせてドキュメント化したファイル群を置く場所を示す。 |
Modeタブは、ソースに書き込んだドキュメントの形式を教える。
ここでは、以下のようにしてみた。
| Select the desired extraction mode | 多分、ドキュメント化の範囲。 ここでは、"Document entities only"にしてある。"All entities"とか"Include cross-referenced source code in the output"にチェックを入れると、ドキュメントに より多くのソース情報を含ませるハズ |
| Select programming language to optimize the result for | ソースに書き込んだドキュメント形式を教えろと言っているハズ。 ここでは、"Optimize for Java Output"としているのは、Special documentation blocks in Pythonここに設定ファイルに、"OPTIMIZE_OUTPUT_JAVA"って設定しろとあったから |
Outputタブは、出力するドキュメントの種類を指定する。
ここでは、以下のようにしてみた。
| HTML | チェック入れるとHTMLファイルを出力する。ここでは、閲覧性に優れる HTML Help形式(.chm)が欲しかったので、"prepare for compressed HTML"を選んだ |
| Man pages | Unixで有名な man 形式ね |
| Rich Text Format(RTF) | Wordで読み取れる形式ね |
| XML | XMLファイル形式ね |
Diagramsタブは、クラス構造を図化する種類を指定する。
ここでは、以下のようにしてみた。
| Diagrams to generate | ここでは、上で折角 Graphviz 入れたので、"Use dot tool from the Graphviz package to generate"を選んでみた。 図なんか要らねぇって場合は、"No diagrams"とか選べばOKのハズ |
4.doxygenに喰わせる
設定したら、"Save"ボタンで設定内容をファイルとして保存し、"Start"ボタンを押せば、ガガガーっと解析してドキュメントファイルを出力してくれる。
ちなみに、ElementTree程度だと、10秒もかからずに終了しちゃう。便利っすな。
ドキュメント化させると、以下のようなフォルダ構造になる。
$ tree
F:.
└─doxygen
├─html
├─man
│ └─man3
├─rtf
└─xml
5.ドキュメントの結果
試しに、HTMLファイル形式の奴を見てみる。
これがトップページ。
doxygen posted from フォト蔵
クラス一覧にしてくれたり。
doxygen posted from フォト蔵
クラス構造を図化してくれたり。
(ここではフラットになっているけど、親子関係を示していると、ちゃんとそれなりの表示をする)
doxygen posted from フォト蔵
メンバーリストを表示してくれたり。
doxygen posted from フォト蔵
ソースに書き込んだドキュメントをリファレンスにしてくれたり。
doxygen posted from フォト蔵
とまぁ、非常に便利。
ちなみに、RTFをWordで読ませると、こんな感じ。
doxygen posted from フォト蔵
6.肝心のHTML Help(.chm)形式はどうよ？
さっきの結果では、肝心の HTML Helpの出力結果が無かったよね。
とはいえ、HTML Help形式のプロジェクトファイルは出力してくれている。HTMLフォルダに、"index.hhp"があるのでダブルクリックすると(HTML Help Workshopをインストールしてないと意味ないよ)、HTML Help Workshopが立ち上がってくれる。
で、おもむろに ビルドボタンを押せば、ちゃっちゃとコンパイルしてくれて…
はい、出来上がり。
ちゃんと、結果表示してるでしょ？
