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

@@ -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!'

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,

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

doc/source/api.rst

@@ -0,0 +1,6 @@
+=========
+ Web API
+=========
+
+.. autoflask:: ceilometer.api.app:app
+   :undoc-static:

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
 

doc/source/index.rst

@@ -50,6 +50,7 @@ Table of contents
    measurements
    install
    configuration
+   api
    contributing/index
    glossary