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

続・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 という指定だけ有効になっています(コメント対象をドキュメントに表示させないオプション)

まとめ

reST ベースではあるものの、PHP のドキュメントを Sphinx に埋め込むモジュール、tk.phpautodoc を作りました。
取りあえず動くレベルまで持っていったものの、まだ完成度は高いとはいえません。
(自分のプロジェクトでは使っていますが)

今後気が向いたらもう少し手直しをして sphinxcontrib に持って行こうと思うので、
我こそはと思う方はこのリポジトリまでバグ報告や pull request を送ってくださると非常に助かります。