Merge "Generate api documentation using sphinx and autoflask"

almanach/adapters/api_route_v1.py

@@ -85,6 +85,10 @@ 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
+    """
     logging.info("Get application info")
     return controller.get_application_info()
 
@@ -93,6 +97,21 @@ 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
+    """
     instance = jsonutils.loads(flask.request.data)
     logging.info("Creating instance for tenant %s with data %s", project_id, instance)
     controller.create_instance(
@@ -114,6 +133,15 @@ 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
+    """
     data = jsonutils.loads(flask.request.data)
     logging.info("Deleting instance with id %s with data %s", instance_id, data)
     controller.delete_instance(
@@ -128,6 +156,16 @@ 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
+    """
     instance = jsonutils.loads(flask.request.data)
     logging.info("Resizing instance with id %s with data %s", instance_id, instance)
     controller.resize_instance(
@@ -143,6 +181,18 @@ 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
+    """
     instance = jsonutils.loads(flask.request.data)
     logging.info("Rebuilding instance with id %s with data %s", instance_id, instance)
     controller.rebuild_instance(
@@ -160,6 +210,16 @@ 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.
+    """
     start, end = get_period()
     logging.info("Listing instances between %s and %s", start, end)
     return controller.list_instances(project_id, start, end)
@@ -169,6 +229,20 @@ 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.
+    """
     volume = jsonutils.loads(flask.request.data)
     logging.info("Creating volume for tenant %s with data %s", project_id, volume)
     controller.create_volume(
@@ -188,6 +262,15 @@ 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)
     logging.info("Deleting volume with id %s with data %s", volume_id, data)
     controller.delete_volume(
@@ -202,6 +285,16 @@ 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.
+    """
     volume = jsonutils.loads(flask.request.data)
     logging.info("Resizing volume with id %s with data %s", volume_id, volume)
     controller.resize_volume(
@@ -217,6 +310,16 @@ 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.
+    """
     volume = jsonutils.loads(flask.request.data)
     logging.info("Attaching volume with id %s with data %s", volume_id, volume)
     controller.attach_volume(
@@ -232,6 +335,16 @@ 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
+    :arg datetime date: Y-m-d H:M:S.f
+    :arg dict attachments: The volume attachments
+
+    :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.
+    """
     volume = jsonutils.loads(flask.request.data)
     logging.info("Detaching volume with id %s with data %s", volume_id, volume)
     controller.detach_volume(
@@ -247,6 +360,16 @@ 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.
+    """
     start, end = get_period()
     logging.info("Listing volumes between %s and %s", start, end)
     return controller.list_volumes(project_id, start, end)
@@ -256,6 +379,16 @@ 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.
+    """
     start, end = get_period()
     logging.info("Listing entities between %s and %s", start, end)
     return controller.list_entities(project_id, start, end)
@@ -265,6 +398,16 @@ 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.
+    """
     data = jsonutils.loads(flask.request.data)
     logging.info("Updating instance entity with id %s with data %s", instance_id, data)
     if 'start' in flask.request.args:
@@ -278,6 +421,13 @@ 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
+    """
     logging.info("Does entity with id %s exists", entity_id)
     response = flask.Response('', 404)
     if controller.entity_exists(entity_id=entity_id):
@@ -289,6 +439,13 @@ 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
+    """
     return controller.get_all_entities_by_id(entity_id)
 
 
@@ -296,6 +453,10 @@ def get_entity(entity_id):
 @authenticated
 @to_json
 def list_volume_types():
+    """List volume types.
+
+    :code 200 OK: Volume types exist
+    """
     logging.info("Listing volumes types")
     return controller.list_volume_types()
 
@@ -304,6 +465,14 @@ def list_volume_types():
 @authenticated
 @to_json
 def get_volume_type(type_id):
+    """Get a volume type.
+
+    :arg uuid 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
+    """
     logging.info("Get volumes type for id %s", type_id)
     return controller.get_volume_type(type_id)
 
@@ -312,6 +481,14 @@ def get_volume_type(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
+    """
     volume_type = jsonutils.loads(flask.request.data)
     logging.info("Creating volume type with data '%s'", volume_type)
     controller.create_volume_type(
@@ -325,6 +502,13 @@ def create_volume_type():
 @authenticated
 @to_json
 def delete_volume_type(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.
+    """
     logging.info("Deleting volume type with id '%s'", type_id)
     controller.delete_volume_type(type_id)
     return flask.Response(status=202)

almanach/api.py

@@ -19,13 +19,13 @@ from almanach.adapters import auth_adapter
 from almanach.adapters import database_adapter
 from almanach.core import controller
 
+app = Flask("almanach")
+app.register_blueprint(api_route.api)
+
 
 class AlmanachApi(object):
     def run(self, host, port):
         api_route.controller = controller.Controller(database_adapter.DatabaseAdapter())
         api_route.auth_adapter = auth_adapter.AuthenticationAdapter().factory()
 
-        app = Flask("almanach")
-        app.register_blueprint(api_route.api)
-
         return app.run(host=host, port=port)

doc/source/conf.py

@@ -22,12 +22,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 = [
-    "sphinx.ext.autodoc",
+    'sphinxcontrib.autohttp.flask'
-    "sphinx.ext.doctest",
-    "sphinx.ext.todo",
-    "sphinx.ext.coverage",
-    "sphinx.ext.ifconfig",
-    "sphinx.ext.viewcode",
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy

doc/source/index.rst

@@ -260,3 +260,10 @@ Almanach will process those events:
 - :code:`volume.update.end`
 - :code:`volume.exists`
 - :code:`volume_type.create`
+
+API documentation
+-----------------
+
+.. autoflask:: almanach.api:app
+    :undoc-static:
+    :include-empty-docstring:

test-requirements.txt

@@ -8,5 +8,6 @@ flexmock==0.9.4
 mongomock==2.0.0
 PyHamcrest==1.8.5
 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

tox.ini

@@ -17,7 +17,7 @@ deps = -r{toxinidir}/test-requirements.txt
 commands = flake8 {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = python setup.py build_sphinx --fresh-env
 
 [flake8]
 show-source = True