2012年1月19日

PHPDocumentorの利用方法まとめ

皆さん、こんにちは。笹亀です。

新年、最初のブログになりました。
2012年も張り切っていきたいと思います。

本日は最近よくお世話になっているPHPDocについて書きたいと思います。
PHPDocとはjavadocを利用したことがあるかたならご存知かと思いますが、APIドキュメントを自動生成する便利なツールです。基本的な出力はHTMLで行い、APIのドキュメントとしてよく利用されるものです。

現在はPHPDocではなく、PHPDocumentorとしてPEARパッケージにて提供がされております。インストールもPEARコマンドから簡単にインストールできます。


pear install --alldeps phpdocumentor

インストール後はphpdocコマンドが使用可能になります。とりあえずテストにDoctrineをPHPDoc化してみたいと思います。
※下記は自分の環境にての実行となります（phpdocコマンドがある箇所から実行してください


sasa-no-MacBook-Pro:Desktop sasa$ /opt/local/bin/phpdoc -t ./doctest/doc  -d ./doctest/Doctrine/ -o HTML:Smarty:PHP
　-t: DOCの出力先
　-d:DOCにする対象フォルダ
　-o:出力形式の指定

コマンド実行中にWaringとか結構でたりしますが、うまいことそれなりに作成をしてくれます。

ただ、個人的にデフォルトのものだとデザインがいけてないです。そこでデザインにもこだわりたいというあなたへPHPDocumentorはSmartyを利用しているので、出力するテンプレートを簡単に切り替えができます。
下記に綺麗なデザインのテンプレートを作成したものがございます。
http://www.onigoetz.ch/2010/09/11/new-theme-for-phpdocumentor/

ダウンロードからテンプレートを落とし、ダウンロードしたファイルを適当な箇所で解凍します。
解凍したファイルを下記のPHPDocmentorが格納されている箇所にコピーします。


sasa-no-MacBook-Pro:~ sasa$ ls -al /opt/local/lib/php/PhpDocumentor/phpDocumentor/Converters/HTML/Smarty/Evolve/
HTMLSmartyEvolveConverter.inc  templates/ 
sasa-no-MacBook-Pro:~ sasa$ ls -al /opt/local/lib/php/data/PhpDocumentor/phpDocumentor/Converters/HTML/Smarty/Evolve/
HTMLSmartyEvolveConverter.inc  templates/

設置作業が完了しましたら、設置したテンプレートにてDoctrineをPHPDoc化してみたいと思います。
※下記は自分の環境にての実行となります（phpdocコマンドがある箇所から実行してください


sasa-no-MacBook-Pro:Desktop sasa$ /opt/local/bin/phpdoc -t ./doctest/docEvolve  -d ./doctest/Doctrine/ -o HTML:Smarty/Evolve:default -s on

下記のようにデザインが綺麗なものでPHPDocとして出力されます。デザインにもこだわったPHPDocを出力することで一歩先のクオリティを目指すこともできますｗ

--------------------------補足情報
PHPDocumentorにて日本語を出力する場合は、文字化け問題にぶつかると思います。
HTML化する際にSmartyのテンプレートを使用しておりまして、テンプレートに直書きで「charset=iso-8859-1」などと記載されております。
下記の箇所にデフォルトのテンプレートが格納されており、ここに入っているheader.tplで指定されている文字コードを変更するとデフォルトの出力する際の文字コードを変更できます。


※自分の環境の場合
/opt/local/lib/php/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/templates/
　PEARが入っている箇所のdataフォルダ以下に格納されています
　☓/opt/local/lib/php/PhpDocumentor/phpDocumentor/（こっちには格納されてません
下記のサイトが参考になるかと思います
　http://wikiwiki.jp/yonkoushi2/?PHP%2Fphpdocumentor%A4%CB%A4%C4%A4%A4%A4%C6