phpDocumentor を利用してドキュメントを自動生成

「ドキュメントのメンテナンスとか面倒でやってられない」と思っている方が弊社に多い ので、 「せめて PHPDoc のメンテはやってください。ドキュメント自動生成するから」 と言ってみましたがどうなることやら。

という状況なので、とりあえず弊社のみんなに見てもらいたく phpDocumentor の使い方を簡単にまとめてみました。

実行方法

以下の3つ

PHAR

docker 使ったら死ぬ呪いに掛かっている人はこちら

# phpDocumentor ダウンロード
wget https://phpdoc.org/phpDocumentor.phar
# 実行権限付与
chmod +x phpDocumentor.phar
# グローバルで実行したい
mv phpDocumentor.phar /usr/local/bin/phpDocumentor

# 実行
# -d  ドキュメント出力元
# -t ドキュメント出力先
phpDocumentor -d [path] -t [path]
# example 
# app ディレクトリのドキュメントを documents ディレクトリに出力
# phpDocumentor -d app -t documents

Docker

普段 docker 使っているならコレ一択

# コンテナイメージダウンロード
docker pull phpdoc/phpdoc
# 実行
# -d  ドキュメント出力元
# -t ドキュメント出力先
docker run --rm -v $(pwd):/data phpdoc/phpdoc -d [path] -t [path]
# example 
# app ディレクトリのドキュメントを documents ディレクトリに出力
# docker run --rm -v $(pwd):/data phpdoc/phpdoc -d app -t documents

composer

一応用意されてはいるが、依存関係に関する問題解消が非常に困難のため、使ってほしくない模様。

自動生成されたドキュメントを参照する

ドキュメント自動生成後、-t オプションで指定したディレクトリ内の index.html を参照する

PHPDoc メンテ時に参考に出来そうなサイト

PHPDoc リファレンス

phpDocumentor