続・PHP のドキュメントを Sphinx で書いてみる (phpautodoc を作ってみた) #sphinxjp
去年の12月にPHP のドキュメントを Sphinx で書いてみる (phpautodoc を作ってみた) #sphinxjpという記事を書きました。
その時に、PHP からドキュメントを抽出する phpautodoc というのを作ったのですが、
その後他の作業に夢中になっていたので自分でも使わないまま放置されていました。
ですが、最近ドキュメントを書く時間を作ったので、作りかけの phpautodoc に手を入れて使えるようにパッケージングしてみました。
tk.phpautodoc を使う
phpautodoc は gist に貼りつけたままで自分でも使いづらかったので、
あらためて tk.phpautodoc という名前で公開することにしました。
本来であれば、sphinxcontrib-phpautodoc とかにすべきなんでしょうが、
実験的要素がまだ残っているのでちゃんとした名前は使わないでいます。
作りこみが一段落したら、パッケージ名は変えるつもりです。
既に PyPI に上がっているので、インストールは
$ pip install tk.phpautodoc
もしくは
$ easy_install tk.phpautodoc
だけで済みます。
インストールした後、Sphinx で生成したドキュメントの conf.py に次の行を書き足せば設定はおしまいです。
extensions += ['sphinxcontrib.phpdomain', 'sphinxcontrib_phpautodoc']
使い方
tk.phpautodoc は Sphinx の autodoc (sphinx.ext.autodoc) を真似たインターフェースになっています。
参考にしているのが automodule と autoclass です。
提供しているディレクティブのひとつが phpautomodule です。
reST ファイルの中で
.. phpautomodule:: :filename: path/to/source_code.php :members: :undoc-members:
のように宣言すると、source_code.php の中に宣言されている関数、クラスをリストアップして
ドキュメントを生成します。
たとえば、以下の様な PHP コードがあったとします。
<? /** * ほげほげする関数。 */ function hogehoge($fuga) { # ... } /** * ふーふーするクラス。 */ class Foo { /** ばー変数 */ public int $bar; }
このコードにたいして phpautomodule を実行すると、内部では以下のような reST ドキュメントが生成されます。
.. php:function:: hogehoge($fuga)
ほげほげする関数。
.. php:class:: Foo
ふーふーするクラス。
.. php:attr:: $bar
ばー変数もうひとつのディレクティブが phpautoclass です。こちらは指定したクラスを抽出します。
.. phpautoclass:: MyClass,Foo :filename: path/to/source_code.php :members: :undoc-members:
phpdoc との互換性
phpdoc のことは多少意識したのですが、ほとんど互換性はありません。
コメントはそのまま reST として解釈されるため、phpdoc の記法は無視されます。
唯一 @access private という指定だけ有効になっています(コメント対象をドキュメントに表示させないオプション)
