Sphinxの自動ドキュメント機能を使うと、Pythonプログラムの充実したドキュメントを手軽に作れます。 あなたは、Pythonの関数ドキュメント(docstring)を書くだけで、Sphinxを使ってドキュメントを整形し、多様なフォーマットに変換できます。 このセッションでは、Sphinxのautodoc, autosummaryを利用したドキュメンテーションの方法について紹介します。

Sphinxのautodoc, autosummaryを利用したドキュメンテーションの方法

Sphinxには、Pythonの関数ドキュメント(docstring)からSphinxのドキュメントを自動的に生成するautodoc機能があります。 docstringに関数の説明や利用例を記載したドキュメントを書くことによって、プログラムとドキュメントの位置が近くなり、更新忘れや機能とドキュメントのズレが起こりにくくなります。また、Sphinxの出力を見ることで、docstringに何を書くべきかがわかり、ドキュメントを書くモチベーションとなります。 autodocを使うには、Pythonモジュールや関数を1つ1つ指定する必要がありますが、autosummary拡張はこの作業を自動化してくれます。このためたいていの場合、開発者はAPIを開発したらSphinxのmake htmlを実行するだけで読みやすく整形されたドキュメントを手に入れられます。 Sphinxにはautodocによるドキュメンテーションをサポートする、coverage, doctest といった拡張があります。これによって、ドキュメントを書けていないAPIを確認したり、ドキュメント内のdoctestブロックに書いた関数の利用例と実際の動作が一致しているかを確認出来ます。 このようなautodoc関連の拡張機能を使うことで、SphinxのAPIドキュメント作成は以下のように実施出来ます。 1. make coverage でドキュメント化されていないAPIを確認する 2. 関数等のdocstringにAPIの使い方をdoctest形式を含めて書く 3. make doctest でdoctest部分が実装と合っているか確認する 4. make html 等でHTMLや好きな形式のドキュメントを生成する このセッションでは、autodoc, autosummary, coverage, doctest それぞれの機能の使い方と、プロセスの全体像について紹介します。