Fix warnings in the documentation build

Some of the docstrings pulled into the API documentation
were malformatted, so fix those. Also include the API
documentation in a toctree so it is linked in the
"Contributing" section of the documentation.

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

.gitignore

@@ -12,5 +12,7 @@ ChangeLog
 dist
 *.egg
 ceilometer/versioninfo
-doc/source/api/*.rst
+doc/source/api/ceilometer.*.rst
+doc/source/api/tests.*.rst
+doc/source/api/autoindex.rst
 *.mo

ceilometer/storage/impl_mongodb.py

@@ -36,27 +36,27 @@ LOG = log.getLogger(__name__)
 class MongoDBStorage(base.StorageEngine):
     """Put the data into a MongoDB database
 
-    Collections:
+    Collections::
 
-    - user
-      - { _id: user id
-          source: [ array of source ids reporting for the user ]
-          }
-    - project
-      - { _id: project id
-          source: [ array of source ids reporting for the project ]
-          }
-    - meter
-      - the raw incoming data
-    - resource
-      - the metadata for resources
-      - { _id: uuid of resource,
-          metadata: metadata dictionaries
-          timestamp: datetime of last update
-          user_id: uuid
-          project_id: uuid
-          meter: [ array of {counter_name: string, counter_type: string} ]
-        }
+        - user
+          - { _id: user id
+              source: [ array of source ids reporting for the user ]
+              }
+        - project
+          - { _id: project id
+              source: [ array of source ids reporting for the project ]
+              }
+        - meter
+          - the raw incoming data
+        - resource
+          - the metadata for resources
+          - { _id: uuid of resource,
+              metadata: metadata dictionaries
+              timestamp: datetime of last update
+              user_id: uuid
+              project_id: uuid
+              meter: [ array of {counter_name: string, counter_type: string} ]
+            }
     """
 
     OPTIONS = []

ceilometer/storage/impl_sqlalchemy.py

@@ -33,45 +33,45 @@ LOG = log.getLogger(__name__)
 class SQLAlchemyStorage(base.StorageEngine):
     """Put the data into a SQLAlchemy database
 
-    Tables:
+    Tables::
 
-    - user
-      - { id: user uuid }
-    - source
-      - { id: source id }
-    - project
-      - { id: project uuid }
-    - meter
-      - the raw incoming data
-      - { id: meter id
-          counter_name: counter name
-          user_id: user uuid            (->user.id)
-          project_id: project uuid      (->project.id)
-          resource_id: resource uuid    (->resource.id)
-          resource_metadata: metadata dictionaries
-          counter_type: counter type
-          counter_volume: counter volume
-          timestamp: datetime
-          message_signature: message signature
-          message_id: message uuid
-          }
-    - resource
-      - the metadata for resources
-      - { id: resource uuid
-          resource_metadata: metadata dictionaries
-          received_timestamp: received datetime
-          timestamp: datetime
-          project_id: project uuid      (->project.id)
-          user_id: user uuid            (->user.id)
-          }
-    - sourceassoc
-      - the relationships
-      - { meter_id: meter id            (->meter.id)
-          project_id: project uuid      (->project.id)
-          resource_id: resource uuid    (->resource.id)
-          user_id: user uuid            (->user.id)
-          source_id: source id          (->source.id)
-          }
+        - user
+          - { id: user uuid }
+        - source
+          - { id: source id }
+        - project
+          - { id: project uuid }
+        - meter
+          - the raw incoming data
+          - { id: meter id
+              counter_name: counter name
+              user_id: user uuid            (->user.id)
+              project_id: project uuid      (->project.id)
+              resource_id: resource uuid    (->resource.id)
+              resource_metadata: metadata dictionaries
+              counter_type: counter type
+              counter_volume: counter volume
+              timestamp: datetime
+              message_signature: message signature
+              message_id: message uuid
+              }
+        - resource
+          - the metadata for resources
+          - { id: resource uuid
+              resource_metadata: metadata dictionaries
+              received_timestamp: received datetime
+              timestamp: datetime
+              project_id: project uuid      (->project.id)
+              user_id: user uuid            (->user.id)
+              }
+        - sourceassoc
+          - the relationships
+          - { meter_id: meter id            (->meter.id)
+              project_id: project uuid      (->project.id)
+              resource_id: resource uuid    (->resource.id)
+              user_id: user uuid            (->user.id)
+              source_id: source id          (->source.id)
+              }
     """
 
     OPTIONS = []

ceilometer/storage/impl_test.py

@@ -36,27 +36,27 @@ class TestDBStorage(base.StorageEngine):
 
     This driver is based on MIM, an in-memory version of MongoDB.
 
-    Collections:
+    Collections::
 
-    - user
-      - { _id: user id
-          source: [ array of source ids reporting for the user ]
-          }
-    - project
-      - { _id: project id
-          source: [ array of source ids reporting for the project ]
-          }
-    - meter
-      - the raw incoming data
-    - resource
-      - the metadata for resources
-      - { _id: uuid of resource,
-          metadata: metadata dictionaries
-          timestamp: datetime of last update
-          user_id: uuid
-          project_id: uuid
-          meter: [ array of {counter_name: string, counter_type: string} ]
-        }
+        - user
+          - { _id: user id
+              source: [ array of source ids reporting for the user ]
+              }
+        - project
+          - { _id: project id
+              source: [ array of source ids reporting for the project ]
+              }
+        - meter
+          - the raw incoming data
+        - resource
+          - the metadata for resources
+          - { _id: uuid of resource,
+              metadata: metadata dictionaries
+              timestamp: datetime of last update
+              user_id: uuid
+              project_id: uuid
+              meter: [ array of {counter_name: string, counter_type: string} ]
+            }
     """
 
     OPTIONS = []

doc/source/api/index.rst

@@ -0,0 +1,8 @@
+======================
+Internal API Reference
+======================
+
+.. toctree::
+   :maxdepth: 1
+
+   autoindex

doc/source/contributing/index.rst

@@ -24,3 +24,4 @@
    areas
    source
    plugins
+   ../api/index

doc/source/index.rst

@@ -53,7 +53,6 @@ Table of contents
    webapi/index
    contributing/index
    releasenotes/index
-   api/index
    glossary
 
 .. - installation