Improve python-designateclient docs

* Improve index page to explain the difference between v1 and v2
  CLI support.
* Add a v2 examples page
* Add all supported commands to v2 shell page
* Add a tox task to build the docs
* Fix a bug building the docs with an invalid html_static_path
  config

Change-Id: Ie1e65c2d0cc8ad1b8b258e03114e19a943d1d19c
Closes-Bug: 1572217

7 files changed, 393 insertions, 45 deletions

diff --git a/doc/source/bindings.rst b/doc/source/bindings.rst
index 6795d04..739a504 100644
--- a/doc/source/bindings.rst
+++ b/doc/source/bindings.rst
@@ -1,10 +1,10 @@
-===============
-Python Bindings
-===============
+===========================
+Python Bindings - v1 and v2
+===========================
 
-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.
+The python-designateclient package comes with python bindings for both versions
+of the Designate API: v1 and v2. These can be used to interact with the Designate 
+API from any python program.
 
 Introduction - Bindings v2
 ==========================
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1629dbe..1b2a8a9 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -121,7 +121,7 @@ html_theme_options = {}
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index dd89358..df0b9ff 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -2,12 +2,23 @@
 python-designateclient
 ======================
 
-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`).
+python-designateclient provides python bindings and command line tools for both
+Designate v1 and v2 APIs.
 
-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.
+The :doc:`Python API bindings <bindings>` are provided by the
+:program:`designateclient` module.
+
+There are two separate command line interfaces to work with the two API
+versions:
+
+v2: the designate plugin for the :program:`openstack` command line tool.  More information can be
+found on the :doc:`designate v2 command line tool page <shell-v2>`.
+
+v1: the :program:`designate` command line tool.  More information can be found
+on the :doc:`designate v1 command line tool page <shell>`.
+
+You'll need credentials for an OpenStack cloud that implements the Designate
+API in order to use the client.
 
 Contents
 ======================
@@ -17,9 +28,10 @@ Contents
 
    installation
    bindings
+   shell-v2
+   shell-v2-examples
    shell
    shell-examples
-   shell-v2
    contributing
    functional-tests
 
diff --git a/doc/source/shell-examples.rst b/doc/source/shell-examples.rst
index d7d71ea..509ef62 100644
--- a/doc/source/shell-examples.rst
+++ b/doc/source/shell-examples.rst
@@ -1,6 +1,6 @@
-======================================
-designate command line tool - examples
-======================================
+====================================
+Designate Command Line Tool Examples
+====================================
 
 Using the client against your dev environment
 ---------------------------------------------
diff --git a/doc/source/shell-v2-examples.rst b/doc/source/shell-v2-examples.rst
new file mode 100644
index 0000000..c440eaf
--- /dev/null
+++ b/doc/source/shell-v2-examples.rst
@@ -0,0 +1,235 @@
+====================================
+Openstack Command Line Tool Examples
+====================================
+
+Because command output would make this document long, much of it will be
+omitted from the examples.
+
+Working with Zones
+------------------
+Create a zone with the following command:
+
+.. code-block:: shell-session
+
+   $ openstack zone create --email admin@example.com example.com.
+   +----------------+--------------------------------------+
+   | Field          | Value                                |
+   +----------------+--------------------------------------+
+   | action         | CREATE                               |
+   | created_at     | 2016-04-19T17:44:04.000000           |
+   | description    | None                                 |
+   | email          | admin@example.com                    |
+   | id             | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+   | masters        |                                      |
+   | name           | example.com.                         |
+   | pool_id        | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
+   | project_id     | 123456                               |
+   | serial         | 1461087844                           |
+   | status         | PENDING                              |
+   | transferred_at | None                                 |
+   | ttl            | 3600                                 |
+   | type           | PRIMARY                              |
+   | updated_at     | None                                 |
+   | version        | 1                                    |
+   +----------------+--------------------------------------+
+
+See the new zone in your list of zones with the following command:
+
+.. code-block:: shell-session
+
+   $ openstack zone list
+
+Display a specific zone with either of these commands; most zone commands
+accept either the zone_id or name attribute:
+
+.. code-block:: shell-session
+
+   $ openstack zone show example.com.
+   $ openstack zone show 388814ef-3c5d-415e-a866-5b1d13d78dae
+
+Update the zone with this command:
+
+.. code-block:: shell-session
+
+   $ openstack zone set --description "Description" example.com.
+
+Delete the zone with this command:
+
+.. code-block:: shell-session
+
+   $ openstack zone delete example.com.
+
+Working with Recordsets
+-----------------------
+Using the zone above, create a recordset with the following command:
+
+.. code-block:: shell-session
+
+  $ openstack recordset create example.com. --type A www --records 192.0.2.20
+  +-------------+--------------------------------------+
+  | Field       | Value                                |
+  +-------------+--------------------------------------+
+  | action      | CREATE                               |
+  | created_at  | 2016-04-19T17:51:12.000000           |
+  | description | None                                 |
+  | id          | 180d3574-3c29-4ea2-b6ff-df904bd3f126 |
+  | name        | www.example.com.                     |
+  | records     | 192.0.2.20                           |
+  | status      | PENDING                              |
+  | ttl         | None                                 |
+  | type        | A                                    |
+  | updated_at  | None                                 |
+  | version     | 1                                    |
+  | zone_id     | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+  +-------------+--------------------------------------+
+
+Multiple records can be provided for a specific recordset type:
+
+.. code-block:: shell-session
+
+  $ openstack recordset create example.com. --type A www --records 192.0.2.20 192.0.2.21
+
+See the new recordset in the list of recordsets with the following command:
+
+.. code-block:: shell-session
+
+   $ openstack recordset list example.com.
+
+Display a specific recordset:
+
+.. code-block:: shell-session
+
+   $ openstack recordset show example.com. www.example.com.
+
+Update a specific recordset:
+
+.. code-block:: shell-session
+
+   $ openstack recordset set example.com. www.example.com. --ttl 10000 --records 192.0.2.20 192.0.2.21
+
+Delete a recordset:
+
+.. code-block:: shell-session
+
+   $ openstack recordset delete example.com. www.example.com.
+
+Working with PTR Records
+------------------------
+Reverse DNS for Neutron Floating IPs can be managed with the "ptr" subcommand.
+
+List all PTR records:
+
+.. code-block:: shell-session
+
+   $ openstack ptr record list
+
+Show a PTR record:
+
+.. code-block:: shell-session
+
+   $ openstack ptr record show RegionOne:5c02c519-4928-4a38-bd10-c748c200912f
+
+Create a PTR record:
+
+.. code-block:: shell-session
+
+   $ openstack ptr record set RegionOne:5c02c519-4928-4a38-bd10-c748c200912f mail.example.com.
+
+Delete a PTR record:
+
+.. code-block:: shell-session
+
+   $ openstack ptr record delete RegionOne:5c02c519-4928-4a38-bd10-c748c200912f
+
+Working with Zone Exports
+-------------------------
+Zone exports enable you to save Designate zone information offline.
+
+Create a zone export:
+
+.. code-block:: shell-session
+
+   $ openstack zone export create example.com.
+   +------------+--------------------------------------+
+   | Field      | Value                                |
+   +------------+--------------------------------------+
+   | created_at | 2016-04-19T20:42:16.000000           |
+   | id         | 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5 |
+   | location   | None                                 |
+   | message    | None                                 |
+   | project_id | 123456                               |
+   | status     | PENDING                              |
+   | updated_at | None                                 |
+   | version    | 1                                    |
+   | zone_id    | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+   +------------+--------------------------------------+
+
+List zone exports:
+
+.. code-block:: shell-session
+
+   $ openstack zone export list
+
+Show zone export:
+
+.. code-block:: shell-session
+
+   $ openstack zone export show 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5
+
+Show the zone file for the Zone Export:
+
+.. code-block:: shell-session
+
+   $ openstack zone export showfile 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5 -f value
+   $ORIGIN example.com.
+   $TTL 3600
+
+   example.com.  IN NS ns2.exampleprovider.com.
+   example.com.  IN NS ns1.exampleprovider.com.
+   example.com.  IN SOA ns.exampleprovider.com. admin@example.com 1458678636 7200 300 604800 300
+
+Delete zone export:
+
+.. code-block:: shell-session
+
+   $ openstack zone export delete 6d5acb9d-f3d6-4ed4-96e1-03bc0e405bb5
+
+Working with Zone Imports
+-------------------------
+Zone imports enable you to import a zone into Designate from a file on the filesystem.
+
+Create a zone import from a file:
+
+.. code-block:: shell-session
+
+   $ openstack zone import create zonefile.txt
+   +------------+--------------------------------------+
+   | Field      | Value                                |
+   +------------+--------------------------------------+
+   | created_at | 2016-04-19T20:59:38.000000           |
+   | id         | bab6e152-da9f-4dfc-8a59-3f9710fe4894 |
+   | message    | None                                 |
+   | project_id | 123456                               |
+   | status     | PENDING                              |
+   | updated_at | None                                 |
+   | version    | 1                                    |
+   | zone_id    | None                                 |
+   +------------+--------------------------------------+
+
+List zone imports:
+
+.. code-block:: shell-session
+
+   $ openstack zone import list
+
+Show zone import:
+
+.. code-block:: shell-session
+
+   $ openstack zone import show 839d8041-1960-4d74-8533-118d52218074
+
+Delete zone import:
+
+.. code-block:: shell-session
+
+   $ openstack zone import delete 839d8041-1960-4d74-8533-118d52218074
diff --git a/doc/source/shell-v2.rst b/doc/source/shell-v2.rst
index 86abdb4..68262ac 100644
--- a/doc/source/shell-v2.rst
+++ b/doc/source/shell-v2.rst
@@ -1,43 +1,144 @@
-=============================
-designate v2 cli and examples
-=============================
+=========================================================
+Openstack Command Line Tool (compatible with v2 API only)
+=========================================================
 
-In order to use the v2 you need *python-openstackclient* available.
+The python-designateclient package comes with a plugin for the openstack
+command line tool (installed as :program:`openstack`).  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.
 
-::
-
-    $ pip install python-openstackclient
-
-
-Using the client
-----------------
+Installation
+------------
 
-Source credentials first
+Both *python-openstackclient* and *python-designateclient* must be installed:
 
 ::
 
-    $ source ~/openrc
+    $ pip install python-openstackclient python-designateclient
 
-Or you can use the ~/.config/openstack/clouds.yaml approach.
 
-.. note::
+Configuration
+-------------
 
-    This required you to pass in --os-cloud <cloudname> after the "openstack" part.
+:program:`openstack` requires certain information to talk to the REST API.  An
+in-depth explanation is covered in the
+`Openstack Client configuration documentation`_.
 
-We can now try to create a primary zone
+Using the Command Line Tool
+---------------------------
 
-.. code-block:: shell-session
-
-    $ openstack zone create example.net. --email foo@example.org
-
-Create a A type recordset with some records in it.
+With enough details now in the environment, you can use the
+:program:`openstack` to create a zone and populate it with some records:
 
 .. code-block:: shell-session
 
-    $ openstack recordset create example.net --type A www --records 10.0.0.1 10.0.0.2
-
-Set a PTR record for a Floating IP
+   $ openstack zone create --email admin@example.com example.com.
+   +----------------+--------------------------------------+
+   | Field          | Value                                |
+   +----------------+--------------------------------------+
+   | action         | CREATE                               |
+   | created_at     | 2016-04-19T17:44:04.000000           |
+   | description    | None                                 |
+   | email          | admin@example.com                    |
+   | id             | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+   | masters        |                                      |
+   | name           | example.com.                         |
+   | pool_id        | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
+   | project_id     | 123456                               |
+   | serial         | 1461087844                           |
+   | status         | PENDING                              |
+   | transferred_at | None                                 |
+   | ttl            | 3600                                 |
+   | type           | PRIMARY                              |
+   | updated_at     | None                                 |
+   | version        | 1                                    |
+   +----------------+--------------------------------------+
+
+Now that the zone has been created, we can start adding records.
+
+You'll note that the zone name (example.com) has a trailing ``.``, as per
+the DNS standard, and we didn't set a TTL.
 
 .. code-block:: shell-session
 
-    $ openstack ptr record set RegionOne:5c02c519-4928-4a38-bd10-c748c200912f mail.example.net.
+  $ openstack recordset create --type A --records 192.0.2.20 example.com. www
+  +-------------+--------------------------------------+
+  | Field       | Value                                |
+  +-------------+--------------------------------------+
+  | action      | CREATE                               |
+  | created_at  | 2016-04-19T17:51:12.000000           |
+  | description | None                                 |
+  | id          | 180d3574-3c29-4ea2-b6ff-df904bd3f126 |
+  | name        | www.example.com.                     |
+  | records     | 192.0.2.20                           |
+  | status      | PENDING                              |
+  | ttl         | None                                 |
+  | type        | A                                    |
+  | updated_at  | None                                 |
+  | version     | 1                                    |
+  | zone_id     | 388814ef-3c5d-415e-a866-5b1d13d78dae |
+  +-------------+--------------------------------------+
+
+Designate-specific Subcommands
+------------------------------
+
+Aside from the ``zone create`` and ``recordset create`` subcommands, this is
+the full list of subcommands that enable Designate V2 support:
+
+============================  ====================================================== ===============
+subcommand                    Notes                                                  Admin Required
+============================  ====================================================== ===============
+zone create                   Create new zone
+zone list                     List zones
+zone show                     Show zone details
+zone set                      Set zone properties
+zone delete                   Delete zone
+recordset create              Create new recordset
+recordset list                List recordsets
+recordset show                Show recordset details
+recordset set                 Set recordset properties
+recordset delete              Delete recordset
+ptr record list               List floatingip ptr records
+ptr record show               Show floatingip ptr record details
+ptr record set                Set floatingip ptr record
+ptr record unset              Unset floatingip ptr record
+zone export create            Export a Zone
+zone export list              List Zone Exports
+zone export show              Show a Zone Export
+zone export delete            Delete a Zone Export
+zone export showfile          Show the zone file for the Zone Export
+zone import create            Import a Zone from a file on the filesystem
+zone import list              List Zone Imports
+zone import show              Show a Zone Import
+zone import delete            Delete a Zone Import
+zone transfer request create  Create new zone transfer request
+zone transfer request list    List Zone Transfer Requests
+zone transfer request show    Show Zone Transfer Request Details
+zone transfer request set     Set a Zone Transfer Request
+zone transfer request delete  Delete a Zone Transfer Request
+zone transfer accept request  Accept a Zone Transfer Request
+zone transfer accept show     Show Zone Transfer Accept
+zone abandon                  Abandon a zone
+zone axfr                     AXFR a zone
+zone blacklist create         Create new blacklist                                   Yes
+zone blacklist list           List blacklists                                        Yes
+zone blacklist show           Show blacklist details                                 Yes
+zone blacklist set            Set blacklist properties                               Yes
+zone blacklist delete         Delete blacklist                                       Yes
+tld create                    Create new tld                                         Yes
+tld list                      List tlds                                              Yes
+tld show                      Show tld details                                       Yes
+tld set                       Set tld properties                                     Yes
+tld delete                    Delete tld                                             Yes
+============================  ====================================================== ===============
+
+Built-in Designate Documentation
+--------------------------------
+
+You'll find complete documentation on the shell by running:
+``openstack --help``
+
+For a specific command, you can execute: ``openstack subcommand help``
+
+.. _Openstack Client configuration documentation: http://docs.openstack.org/developer/python-openstackclient/configuration.html
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
index 1e9e8d3..85f7e5f 100644
--- a/doc/source/shell.rst
+++ b/doc/source/shell.rst
@@ -1,6 +1,6 @@
-===========================
-designate command line tool
-===========================
+=========================================================
+Designate Command Line Tool (compatible with v1 API only)
+=========================================================
 
 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