Add Python bindings docs

Change-Id: I95a098190917017b010a323403ca43108f078958

doc/source/api-examples.rst

@@ -1,5 +0,0 @@
-========================================
-designateclient python module - examples
-========================================
-
-TODO

doc/source/api.rst

@@ -1,4 +0,0 @@
-designateclient python module
-=============================
-
-TODO

doc/source/bindings.rst

@@ -0,0 +1,476 @@
+===============
+Python Bindings
+===============
+
+The python-designateclient package comes with python bindings for the Designate
+API. This can be used to interact with the Designate API from any python
+program.
+
+Introduction
+============
+
+Below is a simple example of how to instantiate and perform basic tasks using
+the bindings.
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client, providing the necessary credentials
+   client = Client(
+       auth_url="https://example.com:5000/v2.0/",
+       username="openstack",
+       password="yadayada",
+       tenant_id="123456789"
+   )
+
+   # Fetch a list of the domains this user/tenant has access to
+   domains = client.domains.list()
+
+   # Iterate the list, printing some useful information
+   for domain in domains:
+       print "Domain ID: %s, Name: %s" % (domain.id, domain.name)
+
+And the output this program might produce:
+
+.. code-block:: console
+
+   $ python /tmp/example.py
+   Domain ID: 467f97b4-f074-4839-ae85-1a61fccfb83d, Name: example-one.com.
+   Domain ID: 6d3bf479-8a93-47ae-8c65-3dff8dba1b0d, Name: example-two.com.
+
+
+Authentication
+==============
+
+Designate supports either Keystone authentication, or no authentication at all.
+
+Keystone Authentication
+-----------------------
+
+Below is a sample of standard authentication with keystone:
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client, providing the necessary credentials
+   client = Client(
+       auth_url="https://example.com:5000/v2.0/",
+       username="openstack",
+       password="yadayada",
+       tenant_id="123456789"
+   )
+
+Below is a sample of standard authentication with keystone, but also explicitly
+providing the endpoint to use:
+
+.. note:: This is useful when a development Designate instances authenticates
+          against a production Keystone.
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client, providing the necessary credentials
+   client = Client(
+       auth_url="https://example.com:5000/v2.0/",
+       username="openstack",
+       password="yadayada",
+       tenant_id="123456789",
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+No Authentication
+-----------------
+
+Below is a sample of interaction with a non authenticated designate:
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client, providing the endpoint directly
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+Working with Domains
+====================
+
+The Domain Object
+-----------------
+
+Object Properties:
+
+======================= =======================================================
+Property                Description
+======================= =======================================================
+id                      Domain ID
+name                    Domain Name (e.g. example.com.)
+email                   Domain Responsible Person Email (e.g. fred@example.com)
+ttl                     Default TTL for records
+serial                  Domain Server Number
+created_at              Date and time this domain was created at
+updated_at              Date and time this domain was last updated
+======================= =======================================================
+
+Listing Domains
+---------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   # List All Domains
+   domains = client.domains.list()
+
+Fetching a Domain by ID
+-----------------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Fetch the domain
+   domain = client.domains.get(domain_id)
+
+
+Creating a Domain
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+   from designateclient.v1.domains import Domain
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   # Create a new Domain object
+   domain = Domain(name="example.com.", email="fred@example.com")
+
+   # Send the Create Domain API call
+   domain = client.domains.create(domain)
+
+Updating a Domain
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Fetch the domain
+   domain = client.domains.get(domain_id)
+
+   # Update a value on the Domain
+   domain.ttl = 300
+
+   # Send the Update Domain API call
+   domain = client.domains.update(domain)
+
+Deleting a Domain
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Fetch the domain
+   domains = client.domains.delete(domain_id)
+
+Working with Records
+====================
+
+The Record Object
+-----------------
+
+Object Properties:
+
+======================= =======================================================
+Property                Description
+======================= =======================================================
+id                      Record ID
+domain_id               Domain ID
+name                    Record Name (e.g. example.com.)
+type                    Record Type (e.g. A, AAAA, CNAME, MX, SRV etc)
+data                    Record Data (e.g. 127.0.0.1)
+priority                Rercord Priority (Valid only for MX and SRV records)
+ttl                     Record TTL
+created_at              Date and time this record was created at
+updated_at              Date and time this record was last updated
+======================= =======================================================
+
+Listing Records
+---------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # List All Records
+   records = client.records.list(domain_id)
+
+Fetching a Record by ID
+-----------------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+   record_id = 'bd3e8520-25e0-11e3-8224-0800200c9a66'
+
+   # Fetch the record
+   records = client.records.get(domain_id, record_id)
+
+
+Creating a Record
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+   from designateclient.v1.records import Record
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Create a new Record object
+   record = Record(name="www.example.com.", type="A", content="127.0.0.1")
+
+   # Send the Create Record API call
+   record = client.records.create(domain_id, record)
+
+Updating a Record
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+   record_id = 'bd3e8520-25e0-11e3-8224-0800200c9a66'
+
+   # Fetch the record
+   record = client.records.get(record_id)
+
+   # Update a value on the Record
+   record.ttl = 300
+
+   # Send the Update Record API call
+   record = client.records.update(record)
+
+Deleting a Record
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   domain_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+   record_id = 'bd3e8520-25e0-11e3-8224-0800200c9a66'
+
+   # Fetch the record
+   records = client.records.delete(record_id)
+
+Working with Servers
+====================
+
+The Server Object
+-----------------
+
+Object Properties:
+
+======================= =======================================================
+Property                Description
+======================= =======================================================
+id                      Server ID
+name                    Server Name (e.g. example.com.)
+created_at              Date and time this server was created at
+updated_at              Date and time this server was last updated
+======================= =======================================================
+
+Listing Servers
+---------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   # List All Servers
+   servers = client.servers.list()
+
+Fetching a Server by ID
+-----------------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   server_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Fetch the server
+   server = client.servers.get(server_id)
+
+
+Creating a Server
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+   from designateclient.v1.servers import Server
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   # Create a new Server object
+   server = Server(name="ns1.example.com.")
+
+   # Send the Create Server API call
+   server = client.servers.create(server)
+
+Updating a Server
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   server_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Fetch the server
+   server = client.servers.get(server_id)
+
+   # Update a value on the Server
+   server.name = "ns2.example.com"
+
+   # Send the Update Server API call
+   server = client.servers.update(server)
+
+Deleting a Server
+-----------------
+
+.. code-block:: python
+
+   #!/usr/bin/env python
+
+   from designateclient.v1 import Client
+
+   # Create an instance of the client
+   client = Client(
+       endpoint="https://127.0.0.1:9001/v1/"
+   )
+
+   server_id = 'fb505f10-25df-11e3-8224-0800200c9a66'
+
+   # Fetch the server
+   servers = client.servers.delete(server_id)

doc/source/conf.py

@@ -213,10 +213,7 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
+#man_pages = []
-    ('index', 'designateclient', u'Designate Client Documentation',
-     [u'Managed I.T.'], 1)
-]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False

doc/source/index.rst

@@ -16,8 +16,7 @@ Contents
    :maxdepth: 1
 
    installation
-   api
+   bindings
-   api-examples
    shell
    shell-examples
    contributing

doc/source/shell.rst

@@ -25,7 +25,7 @@ params, but it's easier to just set them as environment variables::
 You will also need to define the authentication url with ``--os-auth-url``
 or set is as an environment variable as well::
 
-    export OS_AUTH_URL=http://example.com:5000/v2.0/
+    export OS_AUTH_URL=https://example.com:5000/v2.0/
 
 Since Keystone can return multiple regions in the Service Catalog, you
 can specify the one you want with ``--os-region-name`` (or