Generate API documentation

As a new user I found navigating the documentation difficult.  The
flow was a bit unclear and searches bring up old versions of API
references that aren't included in the current documentation.

This
 - provides an introduction to the tools similar to other projects
 - generates API references for the v1 and v2 client
 - fixes some minor docstring issues
 - adds doc/* to pep8 tests to check the conf.py

The API generation code is cribbed from python-novaclient

Change-Id: I65772127679d7afd5e7e48ca7872366b01382f21

glanceclient/v2/images.py

@@ -38,10 +38,11 @@ class Controller(object):
         return warlock.model_factory(schema.raw(), schemas.SchemaBasedModel)
 
     def list(self, **kwargs):
-        """Retrieve a listing of Image objects
+        """Retrieve a listing of Image objects.
 
-        :param page_size: Number of images to request in each paginated request
-        :returns generator over list of Images
+        :param page_size: Number of images to request in each
+                          paginated request.
+        :returns: generator over list of Images.
         """
 
         ori_validate_fun = self.model.validate
@@ -183,7 +184,7 @@ class Controller(object):
 
         :param image_id: ID of the image to modify.
         :param remove_props: List of property names to remove
-        :param **kwargs: Image attribute names and their new values.
+        :param \*\*kwargs: Image attribute names and their new values.
         """
         image = self.get(image_id)
         for (key, value) in kwargs.items():