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>

5 files changed, 72 insertions, 41 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index c342ce9..09867dc 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -27,45 +27,6 @@ ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
 sys.path.insert(0, ROOT)
 sys.path.insert(0, BASE_DIR)
 
-
-def gen_ref(ver, title, names):
-    refdir = os.path.join(BASE_DIR, "ref")
-    pkg = "troveclient"
-    if ver:
-        pkg = "%s.%s" % (pkg, ver)
-        refdir = os.path.join(refdir, ver)
-    if not os.path.exists(refdir):
-        os.makedirs(refdir)
-    idxpath = os.path.join(refdir, "index.rst")
-    with open(idxpath, "w") as idx:
-        idx.write(("%(title)s\n"
-                   "%(signs)s\n"+
-                   "\n"
-                   ".. toctree::\n"
-                   "   :maxdepth: 1\n"
-                   "\n") % {"title": title, "signs": "=" * len(title)})
-        for name in names:
-            idx.write("   %s\n" % name)
-            rstpath = os.path.join(refdir, "%s.rst" % name)
-            with open(rstpath, "w") as rst:
-                rst.write(("%(title)s\n"
-                           "%(signs)s\n"
-                           "\n"
-                           ".. automodule:: %(pkg)s.%(name)s\n"
-                           "   :members:\n"
-                           "   :undoc-members:\n"
-                           "   :show-inheritance:\n"
-                           "   :noindex:\n")
-                          % {"title": name.capitalize(),
-                             "signs": "=" * len(name),
-                             "pkg": pkg, "name": name})
-
-gen_ref("v1", "Version 1 API Reference",
-        ["accounts", "backups", "client", "clusters", "configurations",
-         "databases", "datastores", "diagnostics", "flavors",
-         "hosts", "instances", "limits", "management", "metadata",
-         "quota", "root", "security_groups", "shell", "storage", "users"])
-
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 038e406..392e5c9 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -18,8 +18,8 @@
 .. toctree::
    :maxdepth: 2
 
-   usage
-   ref/v1/index
+   user/index
+   reference/index
 
 Indices and tables
 ==================
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000..1d9e914
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,8 @@
+=============================
+ troveclient Reference Guide
+=============================
+
+.. toctree::
+   :maxdepth: 2
+
+   api/autoindex
diff --git a/doc/source/usage.rst b/doc/source/user/api.rst
index 374d155..374d155 100644
--- a/doc/source/usage.rst
+++ b/doc/source/user/api.rst
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