From 093c39b9524acab9bbbde5dce7efa9752822c5d9 Mon Sep 17 00:00:00 2001
From: Doug Hellmann <doug.hellmann@dreamhost.com>
Date: Tue, 7 Aug 2012 10:17:47 -0400
Subject: [PATCH] Add API documentation

Use sphinxcontrib-httpdomain to produce documentation for
the web API. Add docstrings to the exposed functions.

See http://packages.python.org/sphinxcontrib-httpdomain/
for details about the format of the auto-generated
output.

Change-Id: I62edd1d00c048c4bce34711a23686f0089bbf4e7
Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>
---
 ceilometer/api/app.py |  5 -----
 ceilometer/api/v1.py  |  8 ++++++++
 doc/requirements.txt  | 12 ++++++++++++
 doc/source/api.rst    |  6 ++++++
 doc/source/conf.py    |  5 ++++-
 doc/source/index.rst  |  1 +
 6 files changed, 31 insertions(+), 6 deletions(-)
 create mode 100644 doc/requirements.txt
 create mode 100644 doc/source/api.rst

diff --git a/ceilometer/api/app.py b/ceilometer/api/app.py
index e0c414a6c..ebe5bdae8 100644
--- a/ceilometer/api/app.py
+++ b/ceilometer/api/app.py
@@ -36,8 +36,3 @@ def attach_config():
     storage_engine = storage.get_engine(cfg.CONF)
     flask.request.storage_engine = storage_engine
     flask.request.storage_conn = storage_engine.get_connection(cfg.CONF)
-
-
-@app.route('/')
-def hello():
-    return 'Hello World!'
diff --git a/ceilometer/api/v1.py b/ceilometer/api/v1.py
index 6ee1f81fe..9dcc4f94d 100644
--- a/ceilometer/api/v1.py
+++ b/ceilometer/api/v1.py
@@ -40,6 +40,8 @@ blueprint = flask.Blueprint('v1', __name__)
 @blueprint.route('/sources/<source>/users/<user>/resources')
 @blueprint.route('/sources/<source>/projects/<project>/resources')
 def list_resources(source=None, user=None, project=None):
+    """Return a list of resource names.
+    """
     resources = flask.request.storage_conn.get_resources(
         source=source,
         user=user,
@@ -54,6 +56,8 @@ def list_resources(source=None, user=None, project=None):
 @blueprint.route('/users', defaults={'source': None})
 @blueprint.route('/sources/<source>/users')
 def list_users(source):
+    """Return a list of user names.
+    """
     users = flask.request.storage_conn.get_users(source=source)
     return flask.jsonify(users=list(users))
 
@@ -64,6 +68,8 @@ def list_users(source):
 @blueprint.route('/projects', defaults={'source': None})
 @blueprint.route('/sources/<source>/projects')
 def list_projects(source):
+    """Return a list of project names.
+    """
     projects = flask.request.storage_conn.get_projects(source=source)
     return flask.jsonify(projects=list(projects))
 
@@ -97,6 +103,8 @@ def list_events(user=None,
                 source=None,
                 project=None,
                 ):
+    """Return a list of raw metering events.
+    """
     f = storage.EventFilter(user=user,
                             project=project,
                             source=source,
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 000000000..350a4e39e
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,12 @@
+http://tarballs.openstack.org/nova/nova-master.tar.gz
+webob
+kombu
+iso8601
+lockfile
+netaddr
+argparse
+sqlalchemy
+eventlet
+anyjson==0.3.1
+Flask==0.9
+sphinxcontrib-httpdomain
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 000000000..77abbe4fb
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,6 @@
+=========
+ Web API
+=========
+
+.. autoflask:: ceilometer.api.app:app
+   :undoc-static:
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 5ff19f1b4..1ba56a210 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -25,7 +25,10 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.todo',
+              'sphinxcontrib.autohttp.flask',
+              ]
 
 todo_include_todos = True
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2187fc876..1bdbf2648 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -50,6 +50,7 @@ Table of contents
    measurements
    install
    configuration
+   api
    contributing/index
    glossary