どもー。
かわはらです。
今日は、 Sami を実際に使ってみましたので、紹介します。
Sami は、Fabien がつくった、もうひとつの PHP API document generator です。
最近、このツールを実際に使ってみました。大きな理由としては、
PHP5.2対応のライブラリ (PSR-0準拠) にもバッチリ対応可能だったからです。
それもそのはずで、PHP5.2 にも対応できている Twig の API ドキュメントは
これによって作られているわけです。
(ただし、Sami 自体の動作には PHP5.3 以上が必要)
個人的には、 phpDocumentor2 よりシンプルで、導入もしやすくて良しでした。
以下導入法まとめ
事前に、Composer を導入しておきます。
Composer の解説は、こちら。
Sami を入手し、Composer で依存を解決します。
git clone https://github.com/fabpot/Sami
cd Sami
composer update
これで、入手は完了
動くか確認
php sami.php
うごいたお。
試しにドキュメントを作ります。
例では、Twigのドキュメントを作ろうとしています。
Sami でドキュメントを作るには、 PHP の設定ファイルを作る必要があります。
設定ファイルの内容としては Sami\Sami のインスタンスを返すものになります。
<?php
use Sami\Sami;
use Symfony\Component\Finder\Finder;
// 生成対象
$iterator = Finder::create()
->files()
->name('*.php')
->in(__DIR__.'/lib');
;
return new Sami($iterator, array(
'title' => 'Twig API',
// ビルド先とキャッシュ先
'build_dir' => __DIR__.'/apidoc/',
'cache_dir' => __DIR__.'/apidoc_cache/',
// 最初にドキュメントを開いた時に、展開している名前空間の深さ
'default_opened_level' => 2,
// PHP5.2 スタイルのプロジェクトで _ 区切りの名前空間でドキュメントを作るときは true
'simulate_namespaces' => true
));
Sami のコンストラクタの第一引数には、 Finder によって作られた、ソースコードのファイルを取得することができる Iterator か、
または、単純に *.php が入っているディレクトリ名を指定します。
第二引数は設定です。(コメント行参照)
最後に、ドキュメントを生成します。
php /path/to/sami.php update 設定ファイルのパスこれにより、指定した場所にドキュメントができあがります。
かんたん！
他にも、テンプレートをカスタマイズする Twig が書けたり、
設定にバージョン管理周りの設定などを書くこともできるようなので
機能としては十分な気がします。