sphinxcontrib.httpdomainとは？
sphinxはpython製のドキュメント生成ツールであり、
その中でも sphinxcontrib.httpdomain はWebページの仕様について記述するのに特化した拡張です。
手軽にREST APIのドキュメントを作るのには良い感じのモジュールです。
環境構築
まず、sphinxcontrib-httpdomain とついでに Flask をインストール
% pip-2.7 install flask sphinxcontrib-httpdomain % pip-2.7 freeze|egrep -i "sphinx|flask" Flask==0.9 Sphinx==1.2b1 sphinxcontrib-httpdomain==1.1.7
sphinxドキュメントの作成
# 案内にしたがってポチポチやる
% sphinx-quickstart
# conf.pyを編集
% cp source/conf.py{,.orig}
% vim source/conf.py
# 差分はこんな感じ
% diff -U1 source/conf.py.orig source/conf.py
--- source/conf.py.orig 2013-04-03 00:16:16.000000000 +0900
+++ source/conf.py 2013-04-03 00:14:16.000000000 +0900
@@ -28,2 +28,4 @@
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
+#extensions.extend(['sphinxcontrib.httpdomain'])
+extensions.extend(['sphinxcontrib.autohttp.flask'])
あとは、source以下のindex.rstに下のような記述をいれてやるだけ。
sample app
==========
.. autoflask:: myapp:app
:undoc-static:
:include-empty-docstring:
上のコードでは Flask のアプリケーションからドキュメントを自動的に生成しています。
Flaskアプリケーションの各エントリポイントの docstring に sphinxcontrib.httpdomain の仕様に沿ったドキュメントを書いておけばそこからパラメータ、クエリパラメータ、ステータスコードについてのドキュメントを生成します。
そして最後にドキュメントのビルドをします。
PYTHONPATH で source/app のパスを追加しないと上手くビルド出来ないので注意しましょう。
% PYTHONPATH=source/app make html
ビルド結果はこちらです。
まとめ
これでWebアプリから簡単にドキュメントが生成出来るようになりました。
僕はあんまりドキュメント書くことが得意ではないのでこういった仕組みは非常にありがたいなって思います。
