Merge "Write doc without flask autodoc"

almanach/api/v1/routes.py

@@ -88,15 +88,6 @@ def authenticated(api_call):
 @api.route("/info", methods=["GET"])
 @to_json
 def get_info():
-    """Display information about the current version and counts of entities in the database.
-
-    :code 200 OK: Service is available
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/info.json
-        :language: json
-    """
     return app_ctl.get_application_info()
 
 
@@ -104,26 +95,6 @@ def get_info():
 @authenticated
 @to_json
 def create_instance(project_id):
-    """Create an instance for a tenant.
-
-    :arg uuid project_id: Tenant Uuid
-    :arg uuid id: The instance uuid
-    :arg datetime created_at: Y-m-d H:M:S.f
-    :arg uuid flavor: The flavor uuid
-    :arg str os_type: The OS type
-    :arg str os_distro: The OS distro
-    :arg str os_version: The OS version
-    :arg str name: The instance name
-
-    :code 201 Created: Instance successfully created
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If tenant does not exist
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/create_instance-body.json
-        :language: json
-    """
     body = jsonutils.loads(flask.request.data)
     LOG.info("Creating instance for tenant %s with data %s", project_id, body)
 
@@ -145,20 +116,6 @@ def create_instance(project_id):
 @authenticated
 @to_json
 def delete_instance(instance_id):
-    """Delete the instance.
-
-    :arg uuid instance_id: Instance Uuid
-    :arg datetime date: Y-m-d H:M:S.f
-
-    :code 202 Accepted: Instance successfully deleted
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If instance does not exist
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/delete_instance-body.json
-        :language: json
-    """
     data = jsonutils.loads(flask.request.data)
     LOG.info("Deleting instance with id %s with data %s", instance_id, data)
     instance_ctl.delete_instance(
@@ -173,21 +130,6 @@ def delete_instance(instance_id):
 @authenticated
 @to_json
 def resize_instance(instance_id):
-    """Re-size an instance when the instance flavor was changed in OpenStack.
-
-    :arg uuid instance_id: Instance Uuid
-    :arg datetime date: Y-m-d H:M:S.f
-    :arg uuid flavor: The flavor uuid
-
-    :code 200 OK:  Instance successfully re-sized
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If instance does not exist
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/resize_instance-body.json
-        :language: json
-    """
     instance = jsonutils.loads(flask.request.data)
     LOG.info("Resizing instance with id %s with data %s", instance_id, instance)
     instance_ctl.resize_instance(
@@ -203,23 +145,6 @@ def resize_instance(instance_id):
 @authenticated
 @to_json
 def rebuild_instance(instance_id):
-    """Rebuild an instance when the instance image was changed in OpenStack.
-
-    :arg uuid instance_id: Instance Uuid
-    :arg str distro: The OS distro
-    :arg str version: The OS version
-    :arg str os_type: The OS type
-    :arg datetime rebuild_date: Y-m-d H:M:S.f
-
-    :code 200 OK:  Instance successfully rebuilt
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If instance does not exist
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/rebuild_instance-body.json
-        :language: json
-    """
     body = jsonutils.loads(flask.request.data)
     LOG.info("Rebuilding instance with id %s with data %s", instance_id, body)
     instance_ctl.rebuild_instance(
@@ -237,21 +162,6 @@ def rebuild_instance(instance_id):
 @authenticated
 @to_json
 def list_instances(project_id):
-    """List instances for a tenant.
-
-    :arg uuid project_id: Tenant Uuid
-    :arg datetime start: Y-m-d H:M:S.f
-    :arg datetime end: Y-m-d H:M:S.f
-
-    :code 200 OK: instance list exists
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If tenant does not exist.
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/instances.json
-        :language: json
-    """
     start, end = get_period()
     LOG.info("Listing instances between %s and %s", start, end)
     return instance_ctl.list_instances(project_id, start, end)
@@ -261,25 +171,6 @@ def list_instances(project_id):
 @authenticated
 @to_json
 def create_volume(project_id):
-    """Create a volume for a tenant.
-
-    :arg uuid project_id: Tenant Uuid
-    :arg uuid volume_id: The Volume Uuid
-    :arg datetime start: Y-m-d H:M:S.f
-    :arg uuid volume_type: The Volume Type Uuid
-    :arg str size: The Volume Size
-    :arg str volume_name: The Volume Name
-    :arg uuid attached_to: The Instance Uuid the volume is attached to
-
-    :code 201 Created:  Volume successfully created
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If tenant does not exist.
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/create_volume-body.json
-        :language: json
-    """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Creating volume for tenant %s with data %s", project_id, volume)
     volume_ctl.create_volume(
@@ -299,15 +190,6 @@ def create_volume(project_id):
 @authenticated
 @to_json
 def delete_volume(volume_id):
-    """Delete the volume.
-
-    :arg uuid volume_id: Volume Uuid
-    :arg datetime date: Y-m-d H:M:S.f
-
-    :code 202 Accepted: Volume successfully deleted
-    :code 400 Bad Request: If data invalid or missing
-    :code 404 Not Found: If volume does not exist.
-    """
     data = jsonutils.loads(flask.request.data)
     LOG.info("Deleting volume with id %s with data %s", volume_id, data)
     volume_ctl.delete_volume(
@@ -322,21 +204,6 @@ def delete_volume(volume_id):
 @authenticated
 @to_json
 def resize_volume(volume_id):
-    """Re-size a volume when the volume size was changed in OpenStack.
-
-    :arg uuid volume_id: Volume Uuid
-    :arg str size: The size of the volume
-    :arg datetime date: Y-m-d H:M:S.f
-
-    :code 200 OK: Volume successfully re-sized
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If volume does not exist.
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/resize_volume-body.json
-        :language: json
-    """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Resizing volume with id %s with data %s", volume_id, volume)
     volume_ctl.resize_volume(
@@ -352,21 +219,6 @@ def resize_volume(volume_id):
 @authenticated
 @to_json
 def attach_volume(volume_id):
-    """Update the attachments for a volume when the volume attachments have been changed in OpenStack.
-
-    :arg uuid volume_id: Volume Uuid
-    :arg datetime date: Y-m-d H:M:S.f
-    :arg dict attachments: The volume attachments
-
-    :code 200 OK: Volume successfully attached
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If volume does not exist.
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/attach_volume-body.json
-        :language: json
-    """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Attaching volume with id %s with data %s", volume_id, volume)
     volume_ctl.attach_volume(
@@ -382,19 +234,6 @@ def attach_volume(volume_id):
 @authenticated
 @to_json
 def detach_volume(volume_id):
-    """Detaches a volume when the volume is detached in OpenStack.
-
-    :arg uuid volume_id: Volume Uuid
-
-    :code 200 OK: Volume successfully detached
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If volume does not exist.
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/detach_volume-body.json
-        :language: json
-    """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Detaching volume with id %s with data %s", volume_id, volume)
     volume_ctl.detach_volume(
@@ -410,21 +249,6 @@ def detach_volume(volume_id):
 @authenticated
 @to_json
 def list_volumes(project_id):
-    """List volumes for a tenant.
-
-    :arg uuid project_id: Tenant Uuid
-    :arg datetime start: Y-m-d H:M:S.f
-    :arg datetime end: Y-m-d H:M:S.f
-
-    :code 200 OK: volume list exists
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If tenant does not exist.
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/volumes.json
-        :language: json
-    """
     start, end = get_period()
     LOG.info("Listing volumes between %s and %s", start, end)
     return volume_ctl.list_volumes(project_id, start, end)
@@ -434,22 +258,6 @@ def list_volumes(project_id):
 @authenticated
 @to_json
 def list_entity(project_id):
-    """List instances and volumes for a tenant.
-
-    :arg uuid project_id: Tenant Uuid
-    :arg datetime start: Y-m-d H:M:S.f
-    :arg datetime end: Y-m-d H:M:S.f
-
-    :code 200 OK: instances and volumes list exists
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If tenant does not exist.
-
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/entities.json
-        :language: json
-    """
     start, end = get_period()
     LOG.info("Listing entities between %s and %s", start, end)
     return entity_ctl.list_entities(project_id, start, end)
@@ -459,26 +267,6 @@ def list_entity(project_id):
 @authenticated
 @to_json
 def update_instance_entity(instance_id):
-    """Update an instance entity.
-
-    :arg uuid instance_id: Instance Uuid
-    :arg datetime start: Y-m-d H:M:S.f
-    :arg datetime end: Y-m-d H:M:S.f
-
-    :code 200 OK: Entity successfully updated
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If instance does not exist.
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/update_instance_entity-body.json
-        :language: json
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/update_instance_entity.json
-        :language: json
-    """
     data = jsonutils.loads(flask.request.data)
     LOG.info("Updating instance entity with id %s with data %s", instance_id, data)
     if 'start' in flask.request.args:
@@ -492,13 +280,6 @@ def update_instance_entity(instance_id):
 @api.route("/entity/<entity_id>", methods=["HEAD"])
 @authenticated
 def entity_exists(entity_id):
-    """Verify that an entity exists.
-
-    :arg uuid entity_id: Entity Uuid
-
-    :code 200 OK: if the entity exists
-    :code 404 Not Found: if the entity does not exist
-    """
     LOG.info("Does entity with id %s exists", entity_id)
     response = flask.Response('', 404)
     if entity_ctl.entity_exists(entity_id=entity_id):
@@ -510,18 +291,6 @@ def entity_exists(entity_id):
 @authenticated
 @to_json
 def get_entity(entity_id):
-    """Get an entity.
-
-    :arg uuid entity_id: Entity Uuid
-
-    :code 200 OK: Entity exists
-    :code 404 Not Found: If the entity does not exist
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/entity.json
-        :language: json
-    """
     return entity_ctl.get_all_entities_by_id(entity_id)
 
 
@@ -529,15 +298,6 @@ def get_entity(entity_id):
 @authenticated
 @to_json
 def list_volume_types():
-    """List volume types.
-
-    :code 200 OK: Volume types exist
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/volume_types.json
-        :language: json
-    """
     LOG.info("Listing volumes types")
     return volume_type_ctl.list_volume_types()
 
@@ -546,19 +306,6 @@ def list_volume_types():
 @authenticated
 @to_json
 def get_volume_type(volume_type_id):
-    """Get a volume type.
-
-    :arg uuid volume_type_id: Volume Type Uuid
-
-    :code 200 OK: Volume type exists
-    :code 400 Bad Request: If request data has an invalid or missing field
-    :code 404 Not Found: If the volume type does not exist
-
-    Example output:
-
-    .. literalinclude:: ../api_examples/output/volume_type.json
-        :language: json
-    """
     LOG.info("Get volumes type for id %s", volume_type_id)
     return volume_type_ctl.get_volume_type(volume_type_id)
 
@@ -567,19 +314,6 @@ def get_volume_type(volume_type_id):
 @authenticated
 @to_json
 def create_volume_type():
-    """Create a volume type.
-
-    :arg str type_id: The Volume Type id
-    :arg str type_name: The Volume Type name
-
-    :code 201 Created: Volume successfully created
-    :code 400 Bad Request: If request data has an invalid or missing field
-
-    Example input:
-
-    .. literalinclude:: ../api_examples/input/create_volume_type-body.json
-        :language: json
-    """
     volume_type = jsonutils.loads(flask.request.data)
     LOG.info("Creating volume type with data '%s'", volume_type)
     volume_type_ctl.create_volume_type(
@@ -593,13 +327,6 @@ def create_volume_type():
 @authenticated
 @to_json
 def delete_volume_type(volume_type_id):
-    """Delete the volume type.
-
-    :arg uuid type_id: Volume Type Uuid
-
-    :code 202 Accepted: Volume successfully deleted
-    :code 404 Not Found: If volume type does not exist.
-    """
     LOG.info("Deleting volume type with id '%s'", volume_type_id)
     volume_type_ctl.delete_volume_type(volume_type_id)
     return flask.Response(status=202)

doc/api_examples/input/resize_instance-body.json

@@ -1,4 +0,0 @@
-{
-  "flavor": "my_new_flavor",
-  "date": "2016-11-24 17:25:05+00:00"
-}

doc/api_examples/input/update_instance_entity-body.json

@@ -1,4 +0,0 @@
-{
-  "start_date": "2016-11-24T17:25:05.00Z",
-  "end_date": "2016-11-24T17:35:05.00Z"
-}

doc/source/api_examples/input/create_instance-body.json

@@ -2,7 +2,7 @@
   "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
   "id": "460bb2b6-28d6-42c0-9da4-4288dc3025cc",
   "created_at": "2016-11-24 15:15:05+00:00",
-  "flavor": "my_flavor_name",
+  "flavor": "946d7b8f-b20a-4a1d-bf43-567fa27db614",
   "os_type": "linux",
   "os_version": "7",
   "os_distro": "centos",

doc/source/api_examples/input/resize_instance-body.json

@@ -0,0 +1,4 @@
+{
+  "flavor": "173a54a0-fd55-423e-8084-1ef66d1b428a",
+  "date": "2016-11-24 17:25:05+00:00"
+}

doc/source/api_examples/input/update_instance_entity-body.json

@@ -0,0 +1,4 @@
+{
+  "start": "2016-11-24T17:25:05.00Z",
+  "end": "2016-11-24T17:35:05.00Z"
+}

doc/source/api_examples/output/instances.json

@@ -6,7 +6,7 @@
     "last_event": "2016-11-24 15:14:08+00:00",
     "entity_type": "instance",
     "start": "2016-11-24 15:14:08+00:00",
-    "flavor": "my_flavor_name",
+    "flavor": "173a54a0-fd55-423e-8084-1ef66d1b428a",
     "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
     "os": {
       "os_type": "linux",

doc/source/conf.py

@@ -21,9 +21,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
+extensions = []
-    'sphinxcontrib.autohttp.flask'
-]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.

doc/source/index.rst

@@ -247,6 +247,709 @@ Almanach will process those events:
 API documentation
 -----------------
 
-.. autoflask:: almanach.api.main:app
+:code:`GET /volume_types`
-    :undoc-static:
+
-    :include-empty-docstring:
+    List volume types.
+
+    Status Codes:
+
+    - **200 OK** Volume types exist
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/volume_types.json
+            :language: json
+
+:code:`GET /volume_type/<volume_type_id>`
+
+    Get a volume type.
+
+    Status Codes:
+
+    - **200 OK** Volume type exist
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the volume type does not exist
+
+    Request:
+
+       .. list-table::
+              :widths: 22 8 15 55
+              :header-rows: 1
+
+              * - Name
+                - In
+                - Type
+                - Description
+              * - volume_type_id
+                - path
+                - uuid
+                - The Volume Type Uuid
+
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/volume_type.json
+            :language: json
+
+:code:`POST /volume_type`
+
+    Create a volume type.
+
+    Status Codes:
+
+    - **201 Created** Volume type successfully created
+    - **400 Bad Request** If request data has an invalid or missing field
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - type_id
+              - body
+              - uuid
+              - The Volume Type Uuid
+            * - type_name
+              - body
+              - string
+              - The Volume Type Name
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/create_volume_type-body.json
+            :language: json
+
+:code:`DELETE /volume_type/<volume_type_id>`
+
+    Delete a volume type.
+
+    Status Codes:
+
+    - **202 Accepted** Volume type successfully deleted
+    - **404 Not Found** If the volume type does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - volume_type_id
+              - path
+              - uuid
+              - The Volume Type Uuid
+
+:code:`GET /info`
+
+    Display information about the current version and entity counts.
+
+    Status Codes:
+
+    - **200 OK** Service is available
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/info.json
+            :language: json
+
+:code:`POST /project/<project_id>/instance`
+
+    Create an instance.
+
+    Status Codes:
+
+    - **201 Created** Instance successfully created
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If tenant does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - project_id
+              - body
+              - uuid
+              - The Tenant Uuid
+            * - id
+              - body
+              - uuid
+              - The instance Uuid
+            * - created_at
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - flavor
+              - body
+              - uuid
+              - The flavor Uuid
+            * - os_type
+              - body
+              - string
+              - The OS type
+            * - os_distro
+              - body
+              - string
+              - The OS distro
+            * - os_version
+              - body
+              - string
+              - The OS version
+            * - name
+              - body
+              - string
+              - The instance name
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/create_instance-body.json
+            :language: json
+
+:code:`DELETE /instance/<instance_id>`
+
+    Delete an instance.
+
+    Status Codes:
+
+    - **202 Accepted** Instance successfully deleted
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the instance does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - instance_id
+              - path
+              - uuid
+              - The instance Uuid
+            * - date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/delete_instance-body.json
+            :language: json
+
+:code:`PUT /instance/<instance_id>/resize`
+
+    Re-size an instance.
+
+    Status Codes:
+
+    - **202 Accepted** Instance successfully re-sized
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the instance does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - instance_id
+              - path
+              - uuid
+              - The instance Uuid
+            * - date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - flavor
+              - body
+              - uuid
+              - The flavor Uuid
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/resize_instance-body.json
+            :language: json
+
+:code:`PUT /instance/<instance_id>/rebuild`
+
+    Rebuild an instance.
+
+    Status Codes:
+
+    - **202 Accepted** Instance successfully rebuilt
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the instance does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - instance_id
+              - path
+              - uuid
+              - The instance Uuid
+            * - rebuild_date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - os_type
+              - body
+              - string
+              - The OS type
+            * - os_distro
+              - body
+              - string
+              - The OS distro
+            * - os_version
+              - body
+              - string
+              - The OS version
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/rebuild_instance-body.json
+            :language: json
+
+:code:`GET /project/<project_id>/instances`
+
+    List instances for a tenant.
+
+    Status Codes:
+
+    - **200 OK** Instances exist
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the tenant does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - project_id
+              - path
+              - uuid
+              - The Tenant Uuid
+            * - start
+              - path
+              - datetime
+              - Y-m-d H:M:S.f
+            * - end
+              - path
+              - datetime
+              - Y-m-d H:M:S.f
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/instances.json
+            :language: json
+
+:code:`POST /project/<project_id>/volume`
+
+    Create a volume.
+
+    Status Codes:
+
+    - **201 Created** Volume successfully created
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If tenant does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - project_id
+              - body
+              - uuid
+              - The Tenant Uuid
+            * - volume_id
+              - body
+              - uuid
+              - The volume Uuid
+            * - start
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - volume_type
+              - body
+              - uuid
+              - The volume type Uuid
+            * - size
+              - body
+              - string
+              - The volume size
+            * - volume_name
+              - body
+              - string
+              - The volume name
+            * - attached_to
+              - body
+              - uuid
+              - The instance uuid the volume is attached to
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/create_volume-body.json
+            :language: json
+
+:code:`DELETE /volume/<volume_id>`
+
+    Delete a volume.
+
+    Status Codes:
+
+    - **202 Accepted** Volume successfully deleted
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the volume does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - volume_id
+              - path
+              - uuid
+              - The volume Uuid
+            * - date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/delete_volume-body.json
+            :language: json
+
+:code:`PUT /volume/<volume_id>/resize`
+
+    Re-size a volume.
+
+    Status Codes:
+
+    - **202 Accepted** Volume successfully re-sized
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the volume does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - volume_id
+              - path
+              - uuid
+              - The volume Uuid
+            * - date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - size
+              - body
+              - string
+              - The volume size
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/resize_volume-body.json
+            :language: json
+
+:code:`PUT /volume/<volume_id>/attach`
+
+    Update the attachments for a volume.
+
+    Status Codes:
+
+    - **202 Accepted** Volume successfully attached
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the volume does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - volume_id
+              - path
+              - uuid
+              - The volume Uuid
+            * - date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - attachments
+              - body
+              - dict
+              - The volume attachments
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/attach_volume-body.json
+            :language: json
+
+:code:`PUT /volume/<volume_id>/detach`
+
+    Detach a volume.
+
+    Status Codes:
+
+    - **202 Accepted** Volume successfully detached
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the volume does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - volume_id
+              - path
+              - uuid
+              - The volume Uuid
+            * - date
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - attachments
+              - body
+              - dict
+              - The volume attachments
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/detach_volume-body.json
+            :language: json
+
+:code:`GET /project/<project_id>/volumes`
+
+    List volumes for a tenant.
+
+    Status Codes:
+
+    - **200 OK** Volumes exist
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the tenant does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - project_id
+              - path
+              - uuid
+              - The Tenant Uuid
+            * - start
+              - path
+              - datetime
+              - Y-m-d H:M:S.f
+            * - end
+              - path
+              - datetime
+              - Y-m-d H:M:S.f
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/volumes.json
+            :language: json
+
+:code:`GET /project/<project_id>/entities`
+
+    List entities for a tenant.
+
+    Status Codes:
+
+    - **200 OK** Entities exist
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the tenant does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - project_id
+              - path
+              - uuid
+              - The Tenant Uuid
+            * - start
+              - path
+              - datetime
+              - Y-m-d H:M:S.f
+            * - end
+              - path
+              - datetime
+              - Y-m-d H:M:S.f
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/entities.json
+            :language: json
+
+:code:`PUT /entity/instance/<instance_id>`
+
+    Update an instance.
+
+    Status Codes:
+
+    - **202 Accepted** Instance successfully updated
+    - **400 Bad Request** If request data has an invalid or missing field
+    - **404 Not Found** If the instance does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - instance_id
+              - path
+              - uuid
+              - The instance Uuid
+            * - start
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+            * - end
+              - body
+              - datetime
+              - Y-m-d H:M:S.f
+
+    Example input:
+
+        .. literalinclude:: api_examples/input/update_instance_entity-body.json
+            :language: json
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/update_instance_entity.json
+            :language: json
+
+:code:`HEAD /entity/<entity_id>`
+
+    Verify that an entity exists.
+
+    Status Codes:
+
+    - **200 OK** Entity exists
+    - **404 Not Found** If the entity does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - entity_id
+              - path
+              - uuid
+              - The Entity Uuid
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/entity.json
+            :language: json
+
+:code:`GET /entity/<entity_id>`
+
+    Get an entity.
+
+    Status Codes:
+
+    - **200 OK** If the entity exists
+    - **404 Not Found** If the entity does not exist
+
+    Request:
+
+       .. list-table::
+            :widths: 22 8 15 55
+            :header-rows: 1
+
+            * - Name
+              - In
+              - Type
+              - Description
+            * - entity_id
+              - path
+              - uuid
+              - The Entity Uuid
+
+    Example output:
+
+        .. literalinclude:: api_examples/output/entity.json
+            :language: json

test-requirements.txt

@@ -2,7 +2,6 @@ mongomock==2.0.0
 nose  # LGPL
 setuptools>=16.0,!=24.0.0  # PSF/ZPL
 sphinx>=1.2.1,!=1.3b1,<1.3  # BSD
-sphinxcontrib-httpdomain  # BSD
 flake8>=2.5.4,<2.6.0  # MIT
 hacking<0.12,>=0.11.0  # Apache-2.0
 testtools>=1.4.0  # MIT