Add Python API Reference documentation

This corrects some typos in earlier documentation patches, removes
outdated API reference documentation, and organizes all API reference
documentation under one chapter.

This also leaves room for future API versions and more specific API
reference documentation being broken out into sub-sections.

Change-Id: I5391a1acc7d1669207b3d10039a196d026216f40

cratonclient/v1/client.py

@@ -21,7 +21,39 @@ from cratonclient.v1 import regions
 
 
 class Client(object):
-    """Craton v1 API Client."""
+    """Craton v1 API Client.
+
+    .. attribute:: cells
+
+        The canonical way to list, get, delete, or update cell objects via a
+        :class:`~cratonclient.v1.cells.CellManager` instance.
+
+    .. attribute:: clouds
+
+        The canonical way to list, get, delete, or update cloud objects via a
+        :class:`~cratonclient.v1.clouds.CloudManager` instance.
+
+    .. attribute:: devices
+
+        The canonical way to list devicess via a
+        :class:`~cratonclient.v1.devices.DeviceManager` instance.
+
+    .. attribute:: hosts
+
+        The canonical way to list, get, delete, or update host objects via a
+        :class:`~cratonclient.v1.hosts.HostManager` instance.
+
+    .. attribute:: projects
+
+        The canonical way to list, get, delete, or update project objects via
+        a :class:`~cratonclient.v1.projects.ProjectManager` instance.
+
+    .. attribute:: regions
+
+        The canonical way to list, get, delete, or update region objects via a
+        :class:`~cratonclient.v1.regions.RegionManager` instance.
+
+    """
 
     def __init__(self, session, url):
         """Initialize our client object with our session and url.

doc/source/api-ref/index.rst

@@ -0,0 +1,95 @@
+====================================
+ Python API Reference Documentation
+====================================
+
+This chapter of python-cratonclient's documentation focuses entirely on
+the API of the different objects involved in the use of cratonclient's
+Python API.
+
+
+Version-less Objects
+====================
+
+.. autoclass:: cratonclient.session.Session
+
+
+v1 API Documentation
+====================
+
+.. autoclass:: cratonclient.v1.client.Client
+
+.. NOTE(sigmavirus24): These could all use the regular ``.. class`` directive
+   instead and document each method and attribute individually. This is a good
+   start instead of trying to document everything all at once.
+
+Cells
+-----
+
+.. autoclass:: cratonclient.v1.cells.Cell
+    :members: get, delete, human_id, is_loaded
+
+.. autoclass:: cratonclient.v1.cells.CellManager
+    :members: create, delete, get, list, update
+
+Clouds
+------
+
+.. autoclass:: cratonclient.v1.clouds.Cloud
+    :members: get, delete, human_id, is_loaded
+
+.. autoclass:: cratonclient.v1.clouds.CloudManager
+    :members: create, delete, get, list, update
+
+Devices
+-------
+
+.. autoclass:: cratonclient.v1.devices.Device
+    :members: get, delete, human_id, is_loaded
+
+.. autoclass:: cratonclient.v1.devices.DeviceManager
+    :members: list
+
+Hosts
+-----
+
+.. autoclass:: cratonclient.v1.hosts.Host
+    :members: get, delete, human_id, is_loaded
+
+.. autoclass:: cratonclient.v1.hosts.HostManager
+    :members: create, delete, get, list, update
+
+Projects
+--------
+
+.. autoclass:: cratonclient.v1.projects.Project
+    :members: get, delete, human_id, is_loaded
+
+.. autoclass:: cratonclient.v1.projects.ProjectManager
+    :members: create, delete, get, list, update
+
+Regions
+-------
+
+.. autoclass:: cratonclient.v1.regions.Region
+    :members: get, delete, human_id, is_loaded
+
+.. autoclass:: cratonclient.v1.regions.RegionManager
+    :members: create, delete, get, list, update
+
+Variables
+---------
+
+.. autoclass:: cratonclient.v1.variables.Variable
+
+.. autoclass:: cratonclient.v1.variables.Variables
+
+.. autoclass:: cratonclient.v1.variables.VariableManager
+    :members: create, delete, get, list, update
+
+
+Authentication Helpers
+======================
+
+.. autofunction:: cratonclient.auth.craton_auth
+
+.. autofunction:: cratonclient.auth.keystone_auth

doc/source/authentication-documentation.rst

@@ -1,7 +0,0 @@
-=================================
- cratonclient.auth Documentation
-=================================
-
-.. autofunction:: cratonclient.auth.craton_auth
-
-.. autofunction:: cratonclient.auth.keystone_auth

doc/source/index.rst

@@ -14,11 +14,10 @@ Contents:
 
    readme
    installation
+   contributing
    shell/index
    usage/index
-   v1-api-documentation
-   authentication-documentation
-   contributing
+   api-ref/index
 
 Specifications for python-cratonclient:
 

doc/source/usage/cells.rst

@@ -18,7 +18,7 @@ allow cratonclient to do handle pagination for us:
    for cell in craton.cells.list():
        print_cell_info(cell)
 
-By default :meth:`~cratonclient.v1.cells.CellsManager.list` will handle
+By default :meth:`~cratonclient.v1.cells.CellManager.list` will handle
 pagination for you. If, instead, you want to handle it yourself you will want
 to do something akin to:
 

doc/source/usage/clouds.rst

@@ -18,7 +18,7 @@ allow cratonclient to do handle pagination for us:
    for cloud in craton.clouds.list():
        print_cloud_info(cloud)
 
-By default :meth:`~cratonclient.v1.clouds.CloudsManager.list` will handle
+By default :meth:`~cratonclient.v1.clouds.CloudManager.list` will handle
 pagination for you. If, instead, you want to handle it yourself you will want
 to do something akin to:
 

doc/source/usage/devices.rst

@@ -28,5 +28,5 @@ allow cratonclient to do handle pagination for us:
    for device in craton.devices.list():
        print_device_info(device)
 
-By default :meth:`~cratonclient.v1.devices.DevicesManager.list` will handle
+By default :meth:`~cratonclient.v1.devices.DeviceManager.list` will handle
 pagination for you.

doc/source/usage/hosts.rst

@@ -18,7 +18,7 @@ allow cratonclient to do handle pagination for us:
    for host in craton.hosts.list():
        print_host_info(host)
 
-By default :meth:`~cratonclient.v1.hosts.HostsManager.list` will handle
+By default :meth:`~cratonclient.v1.hosts.HostManager.list` will handle
 pagination for you. If, instead, you want to handle it yourself you will want
 to do something akin to:
 

doc/source/usage/projects.rst

@@ -18,7 +18,7 @@ allow cratonclient to do handle pagination for us:
    for project in craton.projects.list():
        print_project_info(project)
 
-By default :meth:`~cratonclient.v1.projects.ProjectsManager.list` will handle
+By default :meth:`~cratonclient.v1.projects.ProjectManager.list` will handle
 pagination for you. If, instead, you want to handle it yourself you will want
 to do something akin to:
 

doc/source/usage/regions.rst

@@ -18,7 +18,7 @@ allow cratonclient to do handle pagination for us:
    for region in craton.regions.list():
        print_region_info(region)
 
-By default :meth:`~cratonclient.v1.regions.RegionsManager.list` will handle
+By default :meth:`~cratonclient.v1.regions.RegionManager.list` will handle
 pagination for you. If, instead, you want to handle it yourself you will want
 to do something akin to:
 

doc/source/v1-api-documentation.rst

@@ -1,25 +0,0 @@
-======================
- v1 API Documentation
-======================
-
-.. autoclass:: cratonclient.session.Session
-
-.. autoclass:: cratonclient.v1.client.Client
-
-.. autoclass:: cratonclient.v1.cells.Cell
-    :members: get, delete, human_id, is_loaded
-
-.. autoclass:: cratonclient.v1.cells.CellManager
-    :members: create, delete, get, list, update
-
-.. autoclass:: cratonclient.v1.hosts.Host
-    :members: get, delete, human_id, is_loaded
-
-.. autoclass:: cratonclient.v1.hosts.HostManager
-    :members: create, delete, get, list, update
-
-.. autoclass:: cratonclient.v1.regions.Region
-    :members: get, delete, human_id, is_loaded
-
-.. autoclass:: cratonclient.v1.regions.RegionManager
-    :members: create, delete, get, list, update