sphinxcontrib.httpdomainが結構便利だった。 - uokadaの見逃し三振は嫌いです

sphinxcontrib.httpdomainとは？

sphinxcontrib.httpdomain — Documenting RESTful HTTP APIs — sphinxcontrib-httpdomain v1.1.7 documentation

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

ビルド結果はこちらです。

"サンプルドキュメント on GitHub"

まとめ

これでWebアプリから簡単にドキュメントが生成出来るようになりました。

僕はあんまりドキュメント書くことが得意ではないのでこういった仕組みは非常にありがたいなって思います。