rearrange docs into new standard layout

Also replaces inline reference guide generation with pbr's feature for
doing the same thing.

Refer to
https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
for details.

Change-Id: I0fac75bfe66a1ea30973c2128c054aa2e43c8f8b
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

2 files changed, 197 insertions, 0 deletions

diff --git a/doc/source/user/api.rst b/doc/source/user/api.rst
new file mode 100644
index 0000000..374d155
--- /dev/null
+++ b/doc/source/user/api.rst
@@ -0,0 +1,135 @@
+Using the Client Programmatically
+=================================
+
+Authentication
+--------------
+
+Authenticating is necessary to use every feature of the client.
+
+To create the client, create an instance of the Client class.
+The auth url, username, password, and project name must be specified in the
+call to the constructor.
+
+.. testcode::
+
+    from troveclient.v1 import client
+    tc = client.Client(username="testuser",
+            password="PASSWORD",
+            project_id="test_project",
+            region_name="EAST",
+            auth_url="http://api-server:5000/v2.0")
+
+The default authentication strategy assumes a keystone compliant auth system.
+
+Once you have an authenticated client object you can make calls with it,
+for example:
+
+.. testcode::
+
+    flavors = tc.flavors.list()
+    datastores = tc.datastores.list()
+
+Instances
+---------
+
+The following example creates a 512 MB instance with a 1 GB volume:
+
+.. testcode::
+
+    from troveclient.v1 import client
+    tc = client.Client(username="testuser",
+            password="PASSWORD",
+            project_id="test_project",
+            region_name="EAST",
+            auth_url="http://api-server:5000/v2.0")
+
+    flavor_id = '1'
+    volume = {'size':1}
+    databases = [{"name": "my_db",
+                  "character_set": "latin2",           # These two fields
+                  "collate": "latin2_general_ci"}]     # are optional.
+    datastore = 'mysql'
+    datastore_version = '5.6-104'
+    users = [{"name": "jsmith", "password": "12345",
+              "databases": [{"name": "my_db"}]
+             }]
+    instance = client.instances.create("My Instance", flavor_id, volume,
+                                       databases, users, datastore=datastore,
+                                       datastore_version=datastore_version)
+
+To retrieve the instance, use the "get" method of "instances":
+
+.. testcode::
+
+    updated_instance = client.instances.get(instance.id)
+    print(updated_instance.name)
+    print("   Status=%s Flavor=%s" %
+              (updated_instance.status, updated_instance.flavor['id']))
+
+.. testoutput::
+
+    My Instance
+       Status=BUILD Flavor=1
+
+You can delete an instance by calling "delete" on the instance object itself,
+or by using the delete method on "instances."
+
+.. testcode::
+
+    # Wait for the instance to be ready before we delete it.
+    import time
+    from troveclient.exceptions import NotFound
+
+    while instance.status == "BUILD":
+        instance.get()
+        time.sleep(1)
+    print("Ready in an %s state." % instance.status)
+    instance.delete()
+    # Delete and wait for the instance to go away.
+    while True:
+        try:
+            instance = client.instances.get(instance.id)
+            assert instance.status == "SHUTDOWN"
+        except NotFound:
+            break
+
+.. testoutput::
+
+    Ready in an ACTIVE state.
+
+
+Listing Items and Pagination
+--------------------------------
+
+Lists paginate after twenty items, meaning you'll only get twenty items back
+even if there are more. To see the next set of items, send a marker. The marker
+is a key value (in the case of instances, the ID) which is the non-inclusive
+starting point for all returned items.
+
+The lists returned by the client always include a "next" property. This
+can be used as the "marker" argument to get the next section of the list
+back from the server. If no more items are available, then the next property
+is None.
+
+Pagination applies to all listed objects, like instances, datastores, etc.
+The example below is for instances.
+
+.. testcode::
+
+    # There are currently 30 instances.
+
+    instances = client.instances.list()
+    print(len(instances))
+    print(instances.next is None)
+
+    instances2 = client.instances.list(marker=instances.next)
+    print(len(instances2))
+    print(instances2.next is None)
+
+.. testoutput::
+
+    20
+    False
+    10
+    True
+
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
new file mode 100644
index 0000000..2656e42
--- /dev/null
+++ b/doc/source/user/index.rst
@@ -0,0 +1,62 @@
+=========================
+ Trove Client User Guide
+=========================
+
+Command-line API
+----------------
+
+Installing this package gets you a shell command, ``trove``, that you
+can use to interact with any OpenStack cloud.
+
+You'll need to provide your OpenStack username and password. You can do this
+with the ``--os-username``, ``--os-password`` and  ``--os-tenant-name``
+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
+
+You will also need to define the authentication url with ``--os-auth-url`` and
+the version of the API with ``--os-database-api-version`` (default is version
+1.0).  Or set them as an environment variables as well::
+
+    export OS_AUTH_URL=http://example.com:5000/v2.0/
+    export OS_AUTH_URL=1.0
+
+If you are using Keystone, you need to set the OS_AUTH_URL to the keystone
+endpoint::
+
+        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.
+
+Argument ``--profile`` is available only when the osprofiler lib is installed.
+
+You'll find complete documentation on the shell by running
+``trove help``.
+
+For more details, refer to :doc:`../cli/index`.
+
+Python API
+----------
+
+There's also a complete Python API.
+
+Quick-start using keystone::
+
+    # use v2.0 auth with http://example.com:5000/v2.0/
+    >>> from troveclient.v1 import client
+    >>> nt = client.Client(USERNAME, PASSWORD, TENANT_NAME, AUTH_URL)
+    >>> nt.datastores.list()
+    [...]
+    >>> nt.flavors.list()
+    [...]
+    >>> nt.instances.list()
+    [...]
+
+.. toctree::
+   :maxdepth: 2
+
+   api