Sphinx で自動的にAPIリファレンスを作成したい

今日はこのネタです。タイトルの通りなんですが、PythonでそもそもAPIリファレンス的なドキュメントをどうやって作ったら良いのか知りませんでした。

他の言語であれば下記のようなツールを過去に使った事がありました。

  • Java なら Javadoc
  • Perl なら pod2html
  • PHP なら PHPDocumentor

(今ならもっと賢いツールありそうだけど。。。)

Pythonなら?

ではPythonであればどのような選択肢があるでしょう。調べた限りではまず下記のような選択肢がありました。

javadocやらphpdocmentorやらのように、まるっとソースからHTMLを生成するだけであれば、これで十分かもしれません。ただPythonには Sphinxという便利なドキュメンテーションツールがあるので、できれば、reST で且つSphinx用にアウトプットしてくれるツールが欲しいなと思いました。

Sphinxなら?

Sphinxの場合は「sphinx.ext.autodoc 」というエクステがあり、reSTファイル上に下記のように書く事で、ドキュメント生成時に、ソースのdocstringを読み取ってくれて、それをアウトプットとして反映してくれます。

.. automodule:: hoge.fuga

ただ「autodoc」は 「..automodule::」という記述を自分で、reSTファイルに必要な分だけ埋め込む必要がありました。できればjavadocのように丸っとソースファイルのパスを丸投げして、あとは勝手にreSTファイルにしてもらいたいなぁとか思ってましたが。。。

それ sphinx-apidoc で出来るよ!

あるやん。あるやん。何あきらめてん。ちゃんとドキュメントよまなあかんやん。試合はあきらめたら終わりやで > おれ

どうやらSphinxには1.1あたりから「sphinx-apidoc」というツールが同梱されていて、それを使えば、ソースファイルから丸っと、autodocの記載されたreSTファイル群 or Sphinxプロジェクトを作れるそうです。

簡単使い方

  • Sphinx 1.1.2 を利用して説明します。

大体使い方はこんな感じ、「apps」ディレクトリ以下にPythonアプリが入ってるとして、docs以下にSphinxプロジェクトを作成する感じです。

$ sphinx-apidoc -F -o docs/ apps/ 
  • 「-F」オプション は Sphinxドキュメントを一から作る(sphinx-quickstart) 挙動が含まれます。既に運用しているSphinxドキュメントがあり、単純にreSTファイルだけあればいいよという場合には「-F」オプションはいらないでしょう。
  • 覚えておくと良さそうなオプションは「-f (--force)」オプションでしょうか。既に 出力先のディレクトリに同名のファイルがある場合には、ファイル書き出しの処理をスキップするので毎回上書きしてあげた方が更新漏れがなさそうな気がします。

こんな風になる。

手元の Jinja2のソースに対して、sphinx-apidocを掛けるとこんな感じになりました。

f:id:tell-k:20120117001205p:plain

ファイル構成はこんな感じ

docs/
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── jinja2.rst
├── jinja2.testsuite.res.rst
├── jinja2.testsuite.rst
└── make.bat

余談

  • これで少しは真面目に「docstring」でコメントを書くモチベーションも上がりそうですね。(本当か?)

以上おわり。