From 87a9c75ea3326bd1a7d669b71264b84b7c732164 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Fri, 17 Mar 2017 14:38:02 -0500 Subject: [PATCH] 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 | 34 +++++++- doc/source/api-ref/index.rst | 95 +++++++++++++++++++++ doc/source/authentication-documentation.rst | 7 -- doc/source/index.rst | 5 +- doc/source/usage/cells.rst | 2 +- doc/source/usage/clouds.rst | 2 +- doc/source/usage/devices.rst | 2 +- doc/source/usage/hosts.rst | 2 +- doc/source/usage/projects.rst | 2 +- doc/source/usage/regions.rst | 2 +- doc/source/v1-api-documentation.rst | 25 ------ 11 files changed, 136 insertions(+), 42 deletions(-) create mode 100644 doc/source/api-ref/index.rst delete mode 100644 doc/source/authentication-documentation.rst delete mode 100644 doc/source/v1-api-documentation.rst diff --git a/cratonclient/v1/client.py b/cratonclient/v1/client.py index 050f811..fa1f062 100644 --- a/cratonclient/v1/client.py +++ b/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. diff --git a/doc/source/api-ref/index.rst b/doc/source/api-ref/index.rst new file mode 100644 index 0000000..87230a5 --- /dev/null +++ b/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 diff --git a/doc/source/authentication-documentation.rst b/doc/source/authentication-documentation.rst deleted file mode 100644 index 23a6759..0000000 --- a/doc/source/authentication-documentation.rst +++ /dev/null @@ -1,7 +0,0 @@ -================================= - cratonclient.auth Documentation -================================= - -.. autofunction:: cratonclient.auth.craton_auth - -.. autofunction:: cratonclient.auth.keystone_auth diff --git a/doc/source/index.rst b/doc/source/index.rst index 3993439..edb328d 100644 --- a/doc/source/index.rst +++ b/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: diff --git a/doc/source/usage/cells.rst b/doc/source/usage/cells.rst index d602640..eb1dfdc 100644 --- a/doc/source/usage/cells.rst +++ b/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: diff --git a/doc/source/usage/clouds.rst b/doc/source/usage/clouds.rst index f614b20..fa2b7e6 100644 --- a/doc/source/usage/clouds.rst +++ b/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: diff --git a/doc/source/usage/devices.rst b/doc/source/usage/devices.rst index 7010aba..d617c01 100644 --- a/doc/source/usage/devices.rst +++ b/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. diff --git a/doc/source/usage/hosts.rst b/doc/source/usage/hosts.rst index 304f79d..2db0404 100644 --- a/doc/source/usage/hosts.rst +++ b/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: diff --git a/doc/source/usage/projects.rst b/doc/source/usage/projects.rst index 7de0a14..19e7d24 100644 --- a/doc/source/usage/projects.rst +++ b/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: diff --git a/doc/source/usage/regions.rst b/doc/source/usage/regions.rst index 2f487b8..7173694 100644 --- a/doc/source/usage/regions.rst +++ b/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: diff --git a/doc/source/v1-api-documentation.rst b/doc/source/v1-api-documentation.rst deleted file mode 100644 index 68e3648..0000000 --- a/doc/source/v1-api-documentation.rst +++ /dev/null @@ -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