Add documentation for using Craton Python API

This adds some basic documentation describing how to authenticate
against Craton and provides some preliminary auto-generated
documentation of objects.

Change-Id: I2692a80785662e3193e56b62ed78cbe8de9f6e51

doc/source/contributing.rst

@@ -1,4 +1,5 @@
-============
-Contributing
-============
+==============
+ Contributing
+==============
+
 .. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -14,6 +14,7 @@ Contents:
    readme
    installation
    usage
+   v1-api-documentation
    contributing
 
 Indices and tables

doc/source/installation.rst

@@ -1,6 +1,6 @@
-============
-Installation
-============
+==============
+ Installation
+==============
 
 At the command line::
 

doc/source/usage.rst

@@ -1,7 +1,135 @@
-========
-Usage
-========
+=======================
+ Python API User Guide
+=======================
 
-To use python-cratonclient in a project::
+Once you have installed ``python-cratonclient``, there are a few things you
+need to get started using the Python API:
 
-    import cratonclient
+#. You need to know how to authenticate to the Craton API you wish to talk to
+
+   Some Craton API services will be deployed using Craton's in-built
+   authentication system while others may use Keystone.
+
+#. You need your credentials
+
+#. You need the location of your Craton API service
+
+Let's cover authentication first:
+
+
+Authenticating to Craton
+========================
+
+There are two ways to authenticate to Craton:
+
+#. Using Craton's in-built authentication system (the default)
+
+#. Using Keystone
+
+Craton Authentication
+---------------------
+
+In the Craton Authentication case, you need the URL for the Craton API
+service, your username, project ID, and token. To set up cratonclient for this
+authentication, you need only do the following:
+
+.. code-block:: python
+
+    from cratonclient import session
+    from cratonclient.v1 import client
+
+    craton_session = session.Session(
+        username=USERNAME,
+        password=TOKEN,
+        project_id=PROJECT_ID,
+    )
+
+    craton = client.Client(
+        session=craton_session,
+        url=URL,
+    )
+
+Keystone Authentication
+-----------------------
+
+When authenticating to Craton using Keystone, you need to know:
+
+- the URL to use to authenticate to Keystone which we will refer to as
+  ``AUTH_URL``
+
+- the username
+
+- the password
+
+- the project ID or name
+
+- the user domain ID or name
+
+- and the project domain ID or name
+
+Then, we need to do the following:
+
+.. code-block:: python
+
+    from keystoneauth1.identity.v3 import password as password_auth
+    from keystoneauth1 import session as ksa_session
+
+    from cratonclient import session
+    from cratonclient.v1 import client
+
+    _auth = password_auth.Password(
+        auth_url=AUTH_URL,
+        password=PASSWORD,
+        username=USERNAME,
+        user_domain_name=USER_DOMAIN_NAME,
+        project_name=PROJECT_NAME,
+        project_domain_name=PROJECT_DOMAIN_NAME,
+    )
+    craton_session = session.Session(session=ksa_session.Session(auth=_auth))
+    craton = client.Client(
+        session=craton_session,
+        url=URL,
+    )
+
+
+Communicating with Craton
+=========================
+
+Now that you've configured your authentication method, you can interact with
+your ``craton`` object like so:
+
+.. code-block:: python
+
+    for region in craton.regions.list():
+        print('Region {} contains:'.format(region.name))
+        for host in craton.hosts.list(region_id=region.id):
+            print('    {}'.format(host.name))
+
+
+The Craton API has the following resources:
+
+- Cells
+
+- Hosts
+
+- Network Devices
+
+- Network Interfaces
+
+- Networks
+
+- Projects
+
+- Regions
+
+- Users
+
+Of these:
+
+- Cells
+
+- Hosts
+
+- Regions
+
+Are implemented.

doc/source/v1-api-documentation.rst

@@ -0,0 +1,25 @@
+======================
+ 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

test-requirements.txt

@@ -2,6 +2,7 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
+doc8  # Apache-2.0
 hacking<0.12,>=0.10.0
 flake8_docstrings==0.2.1.post1 # MIT
 coverage>=3.6

tox.ini

@@ -14,7 +14,9 @@ deps =
 commands = python setup.py test --slowest --testr-args='{posargs}'
 
 [testenv:pep8]
-commands = flake8 {posargs}
+commands =
+   flake8 {posargs}
+   doc8 doc/source/
 
 [testenv:venv]
 commands = {posargs}