From 4c4f679fbd9393a6172b3b77a2be6af662c559be Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Tue, 15 Nov 2016 15:18:04 -0600 Subject: [PATCH] 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 | 7 +- doc/source/index.rst | 1 + doc/source/installation.rst | 6 +- doc/source/usage.rst | 138 +++++++++++++++++++++++++++- doc/source/v1-api-documentation.rst | 25 +++++ test-requirements.txt | 1 + tox.ini | 4 +- 7 files changed, 170 insertions(+), 12 deletions(-) create mode 100644 doc/source/v1-api-documentation.rst diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 1728a61..2ca75d1 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,4 +1,5 @@ -============ -Contributing -============ +============== + Contributing +============== + .. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index c5f9c87..0b6c218 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,7 @@ Contents: readme installation usage + v1-api-documentation contributing Indices and tables diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 7289e7b..5d2d299 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,6 +1,6 @@ -============ -Installation -============ +============== + Installation +============== At the command line:: diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 472d0f9..062b6c5 100644 --- a/doc/source/usage.rst +++ b/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. diff --git a/doc/source/v1-api-documentation.rst b/doc/source/v1-api-documentation.rst new file mode 100644 index 0000000..68e3648 --- /dev/null +++ b/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 diff --git a/test-requirements.txt b/test-requirements.txt index 7abbaed..a65da94 100644 --- a/test-requirements.txt +++ b/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 diff --git a/tox.ini b/tox.ini index a35dbaf..c584d68 100644 --- a/tox.ini +++ b/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}