first drop of python-designateclient docs

Change-Id: Iecad349608bdc391b1c8613bac55b37f2719be19

7 files changed, 331 insertions, 8 deletions

diff --git a/doc/source/api-examples.rst b/doc/source/api-examples.rst
new file mode 100644
index 0000000..1ef4985
--- /dev/null
+++ b/doc/source/api-examples.rst
@@ -0,0 +1,5 @@
+========================================
+designateclient python module - examples
+========================================
+
+TODO
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 0000000..986c0e7
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,4 @@
+designateclient python module
+=============================
+
+TODO
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
new file mode 100644
index 0000000..87665cd
--- /dev/null
+++ b/doc/source/contributing.rst
@@ -0,0 +1,33 @@
+Contributing
+============
+
+Code is hosted `on GitHub`_. Submit bugs to the Designate project on
+`Launchpad`_. Submit code to the stackforge/python-designateclient project using
+`Gerrit`_.
+
+.. _on GitHub: https://github.com/stackforge/python-designateclient
+.. _Launchpad: https://launchpad.net/designate
+.. _Gerrit: http://wiki.openstack.org/GerritWorkflow
+
+Here's a quick summary:
+
+Install the git-review package to make life easier
+
+.. code-block:: shell-session
+
+  pip install git-review
+
+Branch, work, & submit:
+
+.. code-block:: shell-session
+
+  # cut a new branch, tracking master
+  git checkout --track -b bug/id origin/master
+  # work work work
+  git add stuff
+  git commit
+  # rebase/squash to a single commit before submitting
+  git rebase -i
+  # submit
+  git-review
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e201836..7d0a1c0 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,16 +1,26 @@
-.. designate documentation master file, created by
-   sphinx-quickstart on Wed Oct 31 18:58:17 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+======================
+python-designateclient
+======================
 
-Welcome to designateclients's documentation!
-===================================
+This is a client for Designate API. There's a :doc:`Python API
+<api>` (the :program:`designateclient` module), and a :doc:`command-line tool
+<shell>` (installed as :program:`designate`).
 
-Contents:
+You'll need credentials for an OpenStack cloud that is implementing the Designate API ,
+such as HP's `Cloud DNS`_, in order to use the designate client.
+
+Contents
+======================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   installation
+   api
+   api-examples
+   shell
+   shell-examples
+   contributing
 
 Indices and tables
 ==================
@@ -19,3 +29,4 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _Cloud DNS: http://www.hpcloud.com/products-services/dns
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
new file mode 100644
index 0000000..41b47ca
--- /dev/null
+++ b/doc/source/installation.rst
@@ -0,0 +1,45 @@
+============
+Installation
+============
+
+Install the client from PyPI
+----------------------------
+The :program:`python-designateclient` package is published on `PyPI`_ and so can be installed using the pip tool, which will manage installing all
+python dependencies:
+
+.. code-block:: shell-session
+
+   pip install python-designateclient
+
+*Warning: the packages on PyPI may lag behind the git repo in functionality.*
+
+Setup the client from source
+----------------------------
+If you want the latest version, straight from github:
+
+.. code-block:: shell-session
+
+    git clone git@github.com:stackforge/python-designateclient.git
+    cd python-designateclient
+    virtualenv .venv
+    . .venv/bin/activate
+    pip install -r requirements.txt -r test-requirements.txt
+    python setup.py install
+
+Setup the client in development mode
+------------------------------------
+
+Installing in development mode allows your to make changes to the source code & test directly without having to re-run the "python setup.py install"
+step.  You can find out more about `Development Mode`_
+
+.. code-block:: shell-session
+
+    git clone git@github.com:stackforge/python-designateclient.git
+    cd python-designateclient
+    virtualenv .venv
+    . .venv/bin/activate
+    pip install -r requirements.txt -r test-requirements.txt
+    python setup.py develop
+
+.. _Development Mode: http://pythonhosted.org/distribute/setuptools.html#development-mode
+.. _PyPI: https://pypi.python.org/pypi/python-designateclient/
diff --git a/doc/source/shell-examples.rst b/doc/source/shell-examples.rst
new file mode 100644
index 0000000..cee605b
--- /dev/null
+++ b/doc/source/shell-examples.rst
@@ -0,0 +1,34 @@
+======================================
+designate command line tool - examples
+======================================
+
+Using the client against your dev environment
+---------------------------------------------
+Typically the designate client talks to Keystone (or a Keystone like service) via the OS_AUTH_URL setting & retrives the designate endpoint from the returned service catalog.  Using ``--os-endpoint`` or ``OS_ENDPOINT`` you can specify the end point directly, this is useful if you want to point the client at a test environment that's running without a full Keystone service.
+
+.. code-block:: shell-session
+
+    $ designate --os-endpoint http://127.0.0.1:9001/v1 server-create --name ns.foo.com.
+    +------------+--------------------------------------+
+    | Field      | Value                                |
+    +------------+--------------------------------------+
+    | created_at | 2013-07-09T13:20:23.664811           |
+    | id         | 1af2d561-b802-44d7-8208-46475dcd45f9 |
+    | name       | ns.foo.com.                          |
+    | updated_at | None                                 |
+    +------------+--------------------------------------+
+
+    $ designate --os-endpoint http://127.0.0.1:9001/v1 domain-create --name testing123.net. --email simon@mccartney.ie
+    +------------+--------------------------------------+
+    | Field      | Value                                |
+    +------------+--------------------------------------+
+    | name       | testing123.net.                      |
+    | created_at | 2013-07-09T13:20:30.826155           |
+    | updated_at | None                                 |
+    | id         | 5c02c519-4928-4a38-bd10-c748c200912f |
+    | ttl        | 3600                                 |
+    | serial     | 1373376030                           |
+    | email      | simon@mccartney.ie                   |
+    +------------+--------------------------------------+
+
+    $ designate --os-endpoint http://127.0.0.1:9001/v1 record-create --name myhost.testing123.net. --type A --data 1.2.3.4 5c02c519-4928-4a38-bd10-c748c200912f
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
new file mode 100644
index 0000000..7368935
--- /dev/null
+++ b/doc/source/shell.rst
@@ -0,0 +1,191 @@
+===========================
+designate command line tool
+===========================
+
+The python-designateclient package comes with a command line tool (installed as :program:`designate`), this can be used to access a Designate API
+without having to manipulate JSON by hand, it can also produce the output in a variety of formats (JSON, CSV) and allow you to select columns to be
+displayed.
+
+Credentials
+-----------
+
+As with any OpenStack utility, :program:`designate` requires certain information to
+talk to the REST API, username, password, auth url (from where the other required
+endpoints are retrieved once you are authenticated).
+
+To provide your access credentials (username, password, tenant name or tenant id)
+you can pass them on the command line with the ``--os-username``, ``--os-password``,  ``--os-tenant-name`` or ``--os-tenant-id``
+params, but it's easier to just set them as environment variables::
+
+    export OS_USERNAME=openstack
+    export OS_PASSWORD=yadayada
+    export OS_TENANT_NAME=myproject
+    export OS_TENANT_ID=123456789
+
+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/
+
+Since Keystone can return multiple regions in the Service Catalog, you
+can specify the one you want with ``--os-region-name`` (or
+``export OS_REGION_NAME``). It defaults to the first in the list returned.
+
+Using the command line tool
+---------------------------
+
+With enough details now in environment, you can use the designate client to create a domain & populate it with some records:
+
+.. code-block:: shell-session
+
+   $ designate domain-create --name doctestdomain.eu. --email admin@doctestdomain.eu
+   +-------------+--------------------------------------+
+   | Field       | Value                                |
+   +-------------+--------------------------------------+
+   | description | None                                 |
+   | created_at  | 2013-09-19T11:45:25.295355           |
+   | updated_at  | None                                 |
+   | email       | admin@doctestdomain.eu               |
+   | ttl         | 3600                                 |
+   | serial      | 1379591125                           |
+   | id          | eacbe2a5-95f1-4a9f-89f5-b9c58009b163 |
+   | name        | doctestdomain.eu.                    |
+   +-------------+--------------------------------------+
+
+You can see more details on the arguments domain-create accepts at the `REST API create-domain`_.
+
+Now that the domain has been created, we can start adding records.
+
+You'll note that the name (www.doctestdomain.eu) has a trailing ``.``, as per the DNS standard, we didn't set a TTL and we had to specify the parent
+zone/domain by domain_id ``eacbe2a5-95f1-4a9f-89f5-b9c58009b163``.
+
+.. code-block:: shell-session
+
+  $  designate record-create eacbe2a5-95f1-4a9f-89f5-b9c58009b163 --name www.doctestdomain.eu. --type A --data 1.2.3.4
+  +-------------+--------------------------------------+
+  | Field       | Value                                |
+  +-------------+--------------------------------------+
+  | name        | www.doctestdomain.eu.                |
+  | data        | 1.2.3.4                              |
+  | created_at  | 2013-09-19T13:44:42.295428           |
+  | updated_at  | None                                 |
+  | id          | 147f6082-8466-4951-8d13-37a10e92b11e |
+  | priority    | None                                 |
+  | ttl         | None                                 |
+  | type        | A                                    |
+  | domain_id   | eacbe2a5-95f1-4a9f-89f5-b9c58009b163 |
+  | description | None                                 |
+  +-------------+--------------------------------------+
+
+subcommands
+-----------
+
+We've already seen the ``domain-create`` and ``record-create`` subcommands, here the full list of subcommands:
+
+======================= ====================================================== ===============
+subcommand              Notes                                                  Admin Required
+======================= ====================================================== ===============
+diagnostics-ping        Ping a service on a given host
+diagnostics-sync-all    Sync Everything
+diagnostics-sync-domain Sync a single Domain
+diagnostics-sync-record Sync a single Record
+domain-create           Create Domain
+domain-delete           Delete Domain
+domain-get              Get Domain
+domain-list             List Domains
+domain-servers-list     List Domain Servers
+domain-update           Update Domain
+help                    print detailed help for another command
+record-create           Create Record
+record-delete           Delete Record
+record-get              Get Record
+record-list             List Records
+record-update           Update Record
+report-count-all        Get count totals for all tenants, domains and records
+report-count-domains    Get counts for total domains
+report-count-records    Get counts for total records
+report-count-tenants    Get counts for total tenants
+report-tenant-domains   Get a list of domains for given tenant
+report-tenants-all      Get list of tenants and domain count for each
+server-create           Create Server
+server-delete           Delete Server
+server-get              Get Server
+server-list             List Servers
+server-update           Update Server
+======================= ====================================================== ===============
+
+Builtin designate documentation
+-------------------------------
+
+You'll find complete documentation on the shell by running
+``designate --help``::
+
+    usage: designate [--version] [-v] [--log-file LOG_FILE] [-q] [-h] [--debug]
+                     [--os-endpoint OS_ENDPOINT] [--os-auth-url OS_AUTH_URL]
+                     [--os-username OS_USERNAME] [--os-password OS_PASSWORD]
+                     [--os-tenant-id OS_TENANT_ID]
+                     [--os-tenant-name OS_TENANT_NAME] [--os-token OS_TOKEN]
+                     [--os-service-type OS_SERVICE_TYPE]
+                     [--os-region-name OS_REGION_NAME]
+                     [--sudo-tenant-id SUDO_TENANT_ID] [--insecure]
+
+    Designate Client
+
+    optional arguments:
+      --version             show program's version number and exit
+      -v, --verbose         Increase verbosity of output. Can be repeated.
+      --log-file LOG_FILE   Specify a file to log output. Disabled by default.
+      -q, --quiet           suppress output except warnings and errors
+      -h, --help            show this help message and exit
+      --debug               show tracebacks on errors
+      --os-endpoint OS_ENDPOINT
+                            Defaults to env[OS_DNS_ENDPOINT]
+      --os-auth-url OS_AUTH_URL
+                            Defaults to env[OS_AUTH_URL]
+      --os-username OS_USERNAME
+                            Defaults to env[OS_USERNAME]
+      --os-password OS_PASSWORD
+                            Defaults to env[OS_PASSWORD]
+      --os-tenant-id OS_TENANT_ID
+                            Defaults to env[OS_TENANT_ID]
+      --os-tenant-name OS_TENANT_NAME
+                            Defaults to env[OS_TENANT_NAME]
+      --os-token OS_TOKEN   Defaults to env[OS_SERVICE_TOKEN]
+      --os-service-type OS_SERVICE_TYPE
+                            Defaults to env[OS_DNS_SERVICE_TYPE], or 'dns'
+      --os-region-name OS_REGION_NAME
+                            Defaults to env[OS_REGION_NAME]
+      --sudo-tenant-id SUDO_TENANT_ID
+                            Defaults to env[DESIGNATE_SUDO_TENANT_ID]
+      --insecure            Explicitly allow 'insecure' SSL requests
+
+    Commands:
+      diagnostics-ping  Ping a service on a given host
+      diagnostics-sync-all  Sync Everything
+      diagnostics-sync-domain  Sync a single Domain
+      diagnostics-sync-record  Sync a single Record
+      domain-create  Create Domain
+      domain-delete  Delete Domain
+      domain-get     Get Domain
+      domain-list    List Domains
+      domain-servers-list  List Domain Servers
+      domain-update  Update Domain
+      help           print detailed help for another command
+      record-create  Create Record
+      record-delete  Delete Record
+      record-get     Get Record
+      record-list    List Records
+      record-update  Update Record
+      report-count-all  Get count totals for all tenants, domains and records
+      report-count-domains  Get counts for total domains
+      report-count-records  Get counts for total records
+      report-count-tenants  Get counts for total tenants
+      report-tenant-domains  Get a list of domains for given tenant
+      report-tenants-all  Get list of tenants and domain count for each
+      server-create  Create Server
+      server-delete  Delete Server
+      server-get     Get Server
+      server-list    List Servers
+      server-update  Update Server
+
+.. _REST API create-domain: https://designate.readthedocs.org/en/latest/rest/domains.html#create-domain