Start updating documentation for V2 API

Move the web API documentation into the 'webapi'
subdirectory to avoid conflicts with the auto-generated
'api' directory contents. Create a v2 doc file
as a placeholder until the automatic documentation
features of WSME are more complete.

blueprint api-server-pecan-wsme

Change-Id: Ide11ad0b4cebb29318b8bb977bc5165334e22a2c
Signed-off-by: Doug Hellmann <doug.hellmann@dreamhost.com>

ceilometer/api/controllers/v2.py

@@ -486,6 +486,11 @@ class Source(Base):
     name = text
     data = {text: text}
 
+    @staticmethod
+    def sample():
+        return Source(name='openstack',
+                      data={'key': 'value'})
+
 
 class SourceController(RestController):
     """Works on resources."""

doc/source/api.rst

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

doc/source/conf.py

@@ -31,8 +31,11 @@ import sys
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.todo',
               'sphinxcontrib.autohttp.flask',
+              'wsme.sphinxext',
               ]
 
+wsme_protocols = ['restjson', 'restxml']
+
 todo_include_todos = True
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/index.rst

@@ -50,9 +50,10 @@ Table of contents
    measurements
    install
    configuration
-   api
+   webapi/index
    contributing/index
    releasenotes/index
+   api/index
    glossary
 
 .. - installation

doc/source/webapi/index.rst

@@ -0,0 +1,9 @@
+=========
+ Web API
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   v1
+   v2

doc/source/webapi/v1.rst

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

doc/source/webapi/v2.rst

@@ -0,0 +1,12 @@
+============
+ V2 Web API
+============
+
+.. default-domain:: wsme
+
+.. root:: ceilometer.api.controllers.root.RootController
+   :webpath:
+
+.. autotype:: ceilometer.api.controllers.v2.Source
+
+.. service:: /v2/sources