Sphinx で自動的にAPIリファレンスを作成したい
今日はこのネタです。タイトルの通りなんですが、PythonでそもそもAPIリファレンス的なドキュメントをどうやって作ったら良いのか知りませんでした。
他の言語であれば下記のようなツールを過去に使った事がありました。
- Java なら Javadoc
- Perl なら pod2html
- PHP なら PHPDocumentor
(今ならもっと賢いツールありそうだけど。。。)
Pythonなら?
ではPythonであればどのような選択肢があるでしょう。調べた限りではまず下記のような選択肢がありました。
- pydoc -w でHTML生成 (pydocで簡単なPythonファイルのドキュメントを作成する)
- Epydocを利用する (Epydoc - 偏った言語信者の垂れ流し)
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を掛けるとこんな感じになりました。
ファイル構成はこんな感じ
docs/ ├── Makefile ├── _build ├── _static ├── _templates ├── conf.py ├── index.rst ├── jinja2.rst ├── jinja2.testsuite.res.rst ├── jinja2.testsuite.rst └── make.bat
余談
- これで少しは真面目に「docstring」でコメントを書くモチベーションも上がりそうですね。(本当か?)
以上おわり。