Improve Python API reference

Change-Id: I081c4fea3eba3e9badbc648cbd6fd169460fbb9b

.gitignore

@@ -44,6 +44,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/api
 
 # pbr generates these
 AUTHORS

almanachclient/keystone_client.py

@@ -31,6 +31,12 @@ class KeystoneClient(object):
         self.user_domain_id = user_domain_id
 
     def get_endpoint_url(self, visibility='admin'):
+        """Get Almanach API URL from Keystone catalog
+
+        :arg str visibility: Service visibility
+        :return: Almanach Endpoint URL
+        :rtype: str
+        """
         keystone = self._get_keystone_client()
         endpoints = keystone.endpoints.list(service=self.service, region=self.region_name)
 

almanachclient/v1/client.py

@@ -29,35 +29,33 @@ class Client(HttpClient):
     def get_info(self):
         """Display information about the current version and counts of entities in the database.
 
-        @:returns dict
+        :rtype: dict
         """
         return self._get('{}/{}/info'.format(self.url, self.api_version))
 
     def get_volume_types(self):
         """List volume types.
 
-        @:returns dict
+        :rtype: list
         """
         return self._get('{}/{}/volume_types'.format(self.url, self.api_version))
 
     def get_volume_type(self, volume_type_id):
         """Get a volume type.
 
-        :arg str volume_type_id: Volume Type Uuid
+        :arg str volume_type_id: Volume Type UUID
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: dict
-        @:returns dict
         """
         return self._get('{}/{}/volume_type/{}'.format(self.url, self.api_version, volume_type_id))
 
     def create_volume_type(self, volume_type_id, volume_type_name):
         """Create a volume type.
 
-        :arg str volume_type_id: The Volume Type id
+        :arg str volume_type_id: The Volume Type ID
         :arg str volume_type_name: The Volume Type name
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: bool
-        @:returns bool
         """
         url = '{}/{}/volume_type'.format(self.url, self.api_version)
         data = {'type_id': volume_type_id, 'type_name': volume_type_name}
@@ -67,10 +65,9 @@ class Client(HttpClient):
     def delete_volume_type(self, volume_type_id):
         """Delete the volume type.
 
-        :arg str volume_type_id: Volume Type Uuid
+        :arg str volume_type_id: Volume Type UUID
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: bool
-        @:returns bool
         """
         self._delete('{}/{}/volume_type/{}'.format(self.url, self.api_version, volume_type_id))
         return True
@@ -78,21 +75,28 @@ class Client(HttpClient):
     def get_volumes(self, tenant_id, start, end):
         """List volumes for a tenant.
 
-        :arg str tenant_id: The Tenant Uuid
+        :arg str tenant_id: The Tenant UUID
-        :arg DateTime start
+        :arg datetime start: Start date
-        :arg DateTime end
+        :arg datetime end: End date
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: list
-        @:returns dict
         """
         url = '{}/{}/project/{}/volumes'.format(self.url, self.api_version, tenant_id)
         params = {'start': self._format_qs_datetime(start), 'end': self._format_qs_datetime(end)}
         return self._get(url, params)
 
-    def resize_volume(self, volume_id, size, date=None):
+    def resize_volume(self, volume_id, size, resize_date=None):
+        """Resize a volume.
+
+        :arg str volume_id: Volume UUID
+        :arg int size: Volume size
+        :arg datetime resize_date: Resize date
+        :raises: ClientError
+        :rtype: bool
+        """
         data = {
             'size': size,
-            'date': self._format_body_datetime(date or datetime.now()),
+            'date': self._format_body_datetime(resize_date or datetime.now()),
         }
 
         self._put('{}/{}/volume/{}/resize'.format(self.url, self.api_version, volume_id), data=data)
@@ -101,12 +105,11 @@ class Client(HttpClient):
     def get_instances(self, tenant_id, start, end):
         """List instances for a tenant.
 
-        :arg str tenant_id: The Tenant Uuid
+        :arg str tenant_id: The Tenant UUID
-        :arg DateTime start
+        :arg datetime start: Start date
-        :arg DateTime end
+        :arg datetime end: End date
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: list
-        @:returns dict
         """
         url = '{}/{}/project/{}/instances'.format(self.url, self.api_version, tenant_id)
         params = {'start': self._format_qs_datetime(start), 'end': self._format_qs_datetime(end)}
@@ -115,15 +118,14 @@ class Client(HttpClient):
     def create_instance(self, tenant_id, instance_id, name, flavor, start, image_meta=None):
         """Create an instance for a tenant.
 
-        :arg str tenant_id: The Tenant Uuid
+        :arg str tenant_id: The Tenant UUID
-        :arg str instance_id: The instance uuid
+        :arg str instance_id: The instance UUID
         :arg str name: The instance name
-        :arg str flavor: The flavor uuid
+        :arg str flavor: The flavor
-        :arg DateTime start
+        :arg datetime start: Start date
         :arg dict image_meta: The OS type, distro and version of the image
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: bool
-        @:returns bool
         """
         url = '{}/{}/project/{}/instance'.format(self.url, self.api_version, tenant_id)
         image_meta = image_meta or {}
@@ -139,40 +141,52 @@ class Client(HttpClient):
         return True
 
     def delete_instance(self, instance_id, end=None):
-        """Delete the instance.
+        """Delete an instance.
 
-        :arg str instance_id: Instance Uuid
+        :arg str instance_id: Instance UUID
-        :arg DateTime end
+        :arg datetime end: End date
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: bool
-        @:returns bool
         """
         data = {'date': self._format_body_datetime(end or datetime.now())}
         self._delete('{}/{}/instance/{}'.format(self.url, self.api_version, instance_id), data=data)
         return True
 
-    def resize_instance(self, instance_id, flavor, date=None):
+    def resize_instance(self, instance_id, flavor, resize_date=None):
+        """Resize an instance.
+
+        :arg str instance_id: Instance UUID
+        :arg str flavor: Flavor
+        :arg datetime resize_date: Resize date
+        :raises: ClientError
+        :rtype: bool
+        """
         data = {
             'flavor': flavor,
-            'date': self._format_body_datetime(date or datetime.now()),
+            'date': self._format_body_datetime(resize_date or datetime.now()),
         }
 
         self._put('{}/{}/instance/{}/resize'.format(self.url, self.api_version, instance_id), data=data)
         return True
 
     def get_entity(self, entity_id):
+        """Get single entity.
+
+        :arg str entity_id: Entity UUID
+        :raises: ClientError
+        :rtype: list
+        """
         url = '{}/{}/entity/{}'.format(self.url, self.api_version, entity_id)
         return self._get(url)
 
     def get_tenant_entities(self, tenant_id, start, end):
         """List instances and volumes for a tenant.
 
-        :arg str tenant_id: Tenant Uuid
+        :arg str tenant_id: Tenant UUID
-        :arg DateTime start
+        :arg datetime start: Start date
-        :arg DateTime end
+        :arg datetime end: End date
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: list
-        @:returns dict
         """
         url = '{}/{}/project/{}/entities'.format(self.url, self.api_version, tenant_id)
         params = {'start': self._format_qs_datetime(start), 'end': self._format_qs_datetime(end)}
@@ -181,14 +195,13 @@ class Client(HttpClient):
     def update_instance_entity(self, instance_id, **kwargs):
         """Update an instance entity.
 
-        :arg str instance_id: Instance Uuid
+        :arg str instance_id: Instance UUID
-        :arg DateTime start
+        :arg datetime start: Start date
-        :arg DateTime end
+        :arg datetime end: End date
-        :arg str flavor: The flavor uuid
+        :arg str flavor: The flavor
         :arg str name: The instance name
-
+        :raises: ClientError
-        :raises ClientError
+        :rtype: dict
-        @:returns dict
         """
         url = '{}/{}/entity/instance/{}'.format(self.url, self.api_version, instance_id)
 

doc/source/usage_api.rst

@@ -1,8 +1,10 @@
-The :mod:`almanachclient` Python API
+Almanach Python API
-====================================
+===================
 
 .. module:: almanachclient
-:synopsis: A python client for the Almanach API.
+    :synopsis: A python client for the Almanach API.
+
+.. currentmodule:: almanachclient
 
 Usage
 -----
@@ -49,3 +51,14 @@ Examples
 
 >>> almanach.delete_instance('f1c2db7b-946e-47a4-b443-914a669a3333')
 >>> almanach.update_instance_entity(instance_id='f1c2db7b-946e-47a4-b443-914a669a2222', start=start_date, end=end_date)
+
+
+Reference
+---------
+
+For more information, see the reference:
+
+.. toctree::
+    :maxdepth: 2
+
+    api/autoindex

doc/source/usage_cli.rst

@@ -155,7 +155,7 @@ Arguments:
 Delete Instance
 ---------------
 
-Usage: :code:`almanach delete-instance <instance_id> --end <end>
+Usage: :code:`almanach delete-instance <instance_id> --end <end>`
 
 .. code:: bash
 
@@ -173,7 +173,7 @@ Arguments:
 Resize Instance
 ---------------
 
-Usage: :code:`almanach resize-instance <instance_id> <flavor> --date <resize_date>
+Usage: :code:`almanach resize-instance <instance_id> <flavor> --date <resize_date>`
 
 .. code:: bash
 
@@ -211,7 +211,7 @@ Arguments:
 Resize Volume
 -------------
 
-Usage: :code:`almanach resize-volume <volume_id> <size> --date <resize_date>
+Usage: :code:`almanach resize-volume <volume_id> <size> --date <resize_date>`
 
 .. code:: bash
 

setup.cfg

@@ -33,7 +33,14 @@ all_files = 1
 [upload_sphinx]
 upload-dir = doc/build/html
 
-[build_releasenotes]
+[pbr]
-all_files = 1
+autodoc_index_modules = true
-build-dir = releasenotes/build
+autodoc_exclude_modules =
-source-dir = releasenotes/source
+    almanachclient.tests.*
+    almanachclient.commands.*
+    almanachclient.http_client
+    almanachclient.shell
+    almanachclient.version
+
+[wheel]
+universal = 1

tox.ini

@@ -19,6 +19,7 @@ commands = flake8 {posargs}
 commands = {posargs}
 
 [testenv:docs]
+basepython = python3
 commands = python setup.py build_sphinx
 
 [testenv:releasenotes]