読者です 読者をやめる 読者になる 読者になる

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

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

Sphinx の autodoc

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

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

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

SphinxPHP ドキュメント

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

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

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

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

.. phpautodoc:: hello.php

PHP ファイルを指定すると、自動的にその文書をパースしてコメントを取得します。
サンプルとして hello.php からコメントを抽出して、HTML に変換したもののキャプチャを貼り付けておきます。
f:id:tk0miya:20121226201931p:plain

sphinxcontrib_phpautodoc の仕組み

完全に力技です。

  • phply をちょこっと書き換えたパーサを使って、PHP ソースをパースします
    • なんと phply はコメントを読み飛ばしてしまうのです…
  • 関数、クラス、メソッドを抽出して Sphinx 文書に取り込みます
    • もし直前にコメントがあれば、それをコメント(reST)として取り込みます

夕方からはじめたので、コメントは phpdoc フォーマットではなく reST で書くことを想定しています。
時間があればもう少し手をかける予定です。

興味があれば使ってみてください :-)