どもー。
かわはらです。

今日は、 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 が書けたり、
設定にバージョン管理周りの設定などを書くこともできるようなので
機能としては十分な気がします。

Posted in PHP.

Leave a reply

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>