|
ずいぶん前にPHPDocを取り上げてあれこれ触ってみましたが、いつの間にかPEARマニュアルからページがなくなっていました。現在ではPHPDocの代わりに、高機能なphpDocumentorがPEARに追加されています。
基本的にはPHPDocと同じ「APIドキュメントを自動生成する」という機能だけなのですが出力形式が多様で、HTMLだけでもデザインテンプレートが何種類も用意されており、pear.php.netにあるAPIドキュメントでも採用されています。HTML以外にもPDF形式やWindowsのヘルプファイル用hhpファイル（別途コンパイルが必要）、はたまたpeardoc用docbookも出力できてしまいます。
今回はインストールからざっとした使い方までやってみました。
まずはインストールです。お決まりのコマンドを叩いてインストールします。2005/07/05現在の最新バージョンは、1.3.0rc3です。このバージョンからPHP5がサポートされています。インストール完了後、PHPのインストールPREFIX（指定しなかった場合は/usr/local）/binに「phpdoc」というコマンドが追加されていることを確認しましょう。今回使用したPHPはPHP4.3.11ですが、インストール時に「--prefix=/usr/local/lib/php4」を付けありますので、パスを適宜読み替えてください。
●phpDocumentorのインストール# /usr/local/lib/php4/bin/pear install --alldeps phpdocumentor
downloading PhpDocumentor-1.3.0RC3.tgz ...
Starting to download PhpDocumentor-1.3.0RC3.tgz (2,711,672 bytes)
..........（長いので中略）..........done: 2,711,672 bytes
downloading XML_Beautifier-1.1.tgz ...
Starting to download XML_Beautifier-1.1.tgz (9,854 bytes)
...done: 9,854 bytes
downloading XML_Util-1.1.1.tgz ...
Starting to download XML_Util-1.1.1.tgz (8,358 bytes)
...done: 8,358 bytes
downloading XML_Parser-1.2.6.tgz ...
Starting to download XML_Parser-1.2.6.tgz (12,944 bytes)
...done: 12,944 bytes
Package 'PEAR' already installed, skipping
Package 'PEAR' already installed, skipping
install ok: XML_Parser 1.2.6
install ok: XML_Util 1.1.1
install ok: XML_Beautifier 1.1
install ok: PhpDocumentor 1.3.0RC3
#
# ls /usr/local/lib/php4/bin/
pear* php* php-config* phpdoc* phpextdist* phpize* scripts/
#
またAPIドキュメントを作ってみる前に、「-h」オプションを付けてどの様なオプションが利用できるかチェックしておきましょう（当然、phpDocumentor本家のリファレンスも見てください）。
●phpDocumentorのヘルプ（抜粋）$ /usr/local/lib/php4/bin/phpdoc -h
PHP Version 4.3.11
phpDocumentor version 1.3.0RC3
Parsing configuration file phpDocumentor.ini...
done
using tokenizer Parser
-f --filename name of file(s) to parse ',' file1,file2.
Can contain complete path and * ? wildcards
-d --directory name of a directory(s) to parse
directory1,directory2
：
-t --target path where to save the generated files
：
-o --output output information to use separated by ','.
Format: output:converter:templatedir like
"HTML:frames:phpedit"
：
You can have multiple directories and multiple files, as well as a combination
of both options
$
オプションをとりあえず4つほど挙げてみましたが、これだけでも充分です。コマンドは以下のようになります。
●phpDocumentorの実行例$ /usr/local/lib/php4/bin/phpdoc -t ./output/ -d ./jp/ -o HTML:Smarty:PHP
早速実際のAPIドキュメントを作ってみます。またもや稚拙のXSLTラッパークラスで試してみました。サンプルソースをダウンロードし適当なディレクトリに展開後、作成されたjpディレクトリと同一階層にoutputディレクトリを作成してください。その後、上記のコマンドを実行すると、PHP本家風のドキュメントができあがります。
-oオプションには、[PEARのインストールディレクトリ]/data/PhpDocumentor/user/*.iniに記載されている以下の値が利用できます。個人的には、HTML:Smarty:PHPとかHTML:frames:earthliが好みですが、みなさんも色々と試してみてください。
●-oオプションの一覧HTML:frames:default, HTML:frames:l0l33t, HTML:frames:phpdoc.de, HTML:frames:phphtmllib,
HTML:frames:earthli,
HTML:frames:DOM/default, HTML:frames:DOM/l0l33t, HTML:frames:DOM/phpdoc.de,
HTML:frames:DOM/phphtmllib, HTML:frames:DOM/earthli
HTML:Smarty:default, HTML:Smarty:PHP, HTML:Smarty:HandS
PDF:default:default, CHM:default:default, XML:DocBook/peardoc2:default
で、生成されたドキュメントで気になることがあります。それは生成されたHTMLのcharsetがiso-8859-1に固定されてしまっているテンプレートがあることです。HTML:frames:*は全てそうなってしまっています。原因は、phpDocumentorの内部でテンプレートエンジンのSmartyを使用しているのですが、そのテンプレートに「ISO-8859-1」とべた書きされてしまっているからです。とりあえず、APIドキュメント生成対象のPHPスクリプトの文字エンコーディングに合わせて、テンプレートのcharsetを書き換えればOKです。修正対象のテンプレートは、[PEARのインストールディレクトリ]/data/PhpDocumentor/phpDocumentor/Convertersの数階層下のtemplatesディレクトリあるheader.tplです。
ここで、上記のディレクトリ構造と-oオプションをよく見てもらうと。。。そうです。-oオプションの値はテンプレートのディレクトリ構造を表していることが分かると思います。なので、具体的にどのオプションでどの様なデザインになるかは、テンプレート側を見ても分かると思います。
もう一つ。デフォルトでドキュメント作成対象となるPHPスクリプトの拡張子は、
の5つです。例えば、拡張子がphp5なPHPスクリプトのAPIドキュメントはどうやって対象とするのか？どこかに設定があるのか？。。。あります。[PEARのインストールディレクトリ]/data/PhpDocumentor/phpDocumentor.iniがデフォルトの設定ファイルになります。この中の_phpDocumentor_phpfile_extsディレクティブに対象としたい拡張子を追加して、phpdocコマンドを実行するだけです。これで「php5」だろうが「phl」だろうが大丈夫です。
とりあえず今回はここまでです。次回はもうちょっと掘り下げて、PDFやCHMもやってみようかと思います。
|