PHP のドキュメントを Sphinx で書いてみる (phpautodoc を作ってみた) #sphinxjp

この記事は Sphinx アドベントカレンダーの 26日目(相当)を勝手に書いたものです。

Sphinx の autodoc

Sphinx には autodoc という機能があります。
未だにうまく使う方法を理解できていないのですが、ちゃんと使うと Python コードに書かれた docstring を元に
Sphinx 文書にリファレンスを埋め込むことができるそうです。
Javadoc や Doxygen のようなことができるということですね。

「Sphinx 文書に埋め込む」というスタイルをとっているため、
コードに記述しづらいシステムの概要やミドルウェアの話、
運用における注意点などは通常どおり Sphinx 文書として記述して、
コードに関する説明などは docstring に書くという書き分けができそうです。

ただ、あまり詳しい説明が書いていないこともあり、
また Python で API リファレンスを必要とする場面に出会わないことなどから、
今まで autodoc を使う機会がなかなかありませんでした。

Sphinx と PHP ドキュメント

そんな折、PHP のコードのメンテナンスのお仕事をすることになりました。
200〜300 行ぐらいのシンプルなコードなので、これまで API ドキュメント(Sphinx)への反映は手作業で行なっていたのですが、
ちょくちょく変更があるため、手間を感じたり、反映漏れなどが心配になってきていました。

そこで、今回 PHP のコメント情報を取り出して Sphinx 文書に埋め込むという、
autodoc っぽいことをやってみることにしました。
しかし、autodoc の仕組みを理解して、部品化していくには時間が掛かりそう(=時間が取れなさそう)だったので、
ad-hoc ではあるものの autodoc とは別のものとして連携機能を作ってみました。
それが phpautodoc です。

gist に最低限の情報は載せたので、それを見ながらセットアップしてください。
ply と phply に依存しているので、合わせてインストールしてください。

設定が終わった後、Sphinx 文書内で