Merge "rearrange docs into new standard layout"

8 files changed, 85 insertions, 345 deletions

diff --git a/.gitignore b/.gitignore
index 7dfa5c3..9f6cf16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,3 +14,5 @@ ChangeLog
 
 # Files created by releasenotes build
 releasenotes/build
+/doc/build/
+/doc/source/reference/api/
diff --git a/README.rst b/README.rst
index 2ba58bc..b407d21 100644
--- a/README.rst
+++ b/README.rst
@@ -16,7 +16,7 @@ This is a client for the OpenStack Trove API. There's a Python API (the
 ``troveclient`` module), and a command-line script (``trove``). Each
 implements 100% of the OpenStack Trove API.
 
-See the `OpenStack CLI guide`_ for information on how to use the ``trove``
+See the `OpenStack CLI Guide`_ for information on how to use the ``trove``
 command-line tool. You may also want to look at the
 `OpenStack API documentation`_.
 
@@ -26,318 +26,18 @@ command-line tool. You may also want to look at the
 python-troveclient is licensed under the Apache License like the rest of OpenStack.
 
 * License: Apache License, Version 2.0
-* `PyPi`_ - package installation
-* `Online Documentation`_
+* Documentation: http://docs.openstack.org/developer/python-troveclient/
+* Bugs: https://bugs.launchpad.net/python-troveclient
+* `PyPi`_- package installation
 * `Blueprints`_ - feature specifications
-* `Bugs`_ - issue tracking
 * `Git Source`_
 * `Github`_
 * `Specs`_
 * `How to Contribute`_
 
 .. _PyPi: https://pypi.python.org/pypi/python-troveclient
-.. _Online Documentation: http://docs.openstack.org/developer/python-troveclient
 .. _Blueprints: https://blueprints.launchpad.net/python-troveclient
-.. _Bugs: https://bugs.launchpad.net/python-troveclient
 .. _Git Source: https://git.openstack.org/cgit/openstack/python-troveclient
 .. _Github: https://github.com/openstack/python-troveclient
 .. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html
 .. _Specs: http://specs.openstack.org/openstack/trove-specs/
-
-.. contents:: Contents:
-   :local:
-
-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``::
-
-    usage: trove [--version] [--debug] [--service-type <service-type>]
-                 [--service-name <service-name>] [--bypass-url <bypass-url>]
-                 [--database-service-name <database-service-name>]
-                 [--endpoint-type <endpoint-type>]
-                 [--os-database-api-version <database-api-ver>]
-                 [--retries <retries>] [--json] [--profile HMAC_KEY] [--insecure]
-                 [--os-cacert <ca-certificate>] [--os-cert <certificate>]
-                 [--os-key <key>] [--timeout <seconds>] [--os-auth-type <name>]
-                 [--os-auth-url OS_AUTH_URL] [--os-domain-id OS_DOMAIN_ID]
-                 [--os-domain-name OS_DOMAIN_NAME] [--os-project-id OS_PROJECT_ID]
-                 [--os-project-name OS_PROJECT_NAME]
-                 [--os-project-domain-id OS_PROJECT_DOMAIN_ID]
-                 [--os-project-domain-name OS_PROJECT_DOMAIN_NAME]
-                 [--os-trust-id OS_TRUST_ID]
-                 [--os-default-domain-id OS_DEFAULT_DOMAIN_ID]
-                 [--os-default-domain-name OS_DEFAULT_DOMAIN_NAME]
-                 [--os-user-id OS_USER_ID] [--os-username OS_USERNAME]
-                 [--os-user-domain-id OS_USER_DOMAIN_ID]
-                 [--os-user-domain-name OS_USER_DOMAIN_NAME]
-                 [--os-password OS_PASSWORD] [--os-region-name <region-name>]
-                 <subcommand> ...
-
-    Command-line interface to the OpenStack Trove API.
-
-    Positional arguments:
-      <subcommand>
-        backup-copy                   Creates a backup from another backup.
-        backup-create                 Creates a backup of an instance.
-        backup-delete                 Deletes a backup.
-        backup-list                   Lists available backups.
-        backup-list-instance          Lists available backups for an instance.
-        backup-show                   Shows details of a backup.
-        cluster-create                Creates a new cluster.
-        cluster-delete                Deletes a cluster.
-        cluster-force-delete          Force delete a cluster
-        cluster-grow                  Adds more instances to a cluster.
-        cluster-instances             Lists all instances of a cluster.
-        cluster-list                  Lists all the clusters.
-        cluster-modules               Lists all modules for each instance of a
-                                      cluster.
-        cluster-reset-status          Set the cluster task to NONE.
-        cluster-show                  Shows details of a cluster.
-        cluster-shrink                Drops instances from a cluster.
-        configuration-attach          Attaches a configuration group to an
-                                      instance.
-        configuration-create          Creates a configuration group.
-        configuration-default         Shows the default configuration of an
-                                      instance.
-        configuration-delete          Deletes a configuration group.
-        configuration-detach          Detaches a configuration group from an
-                                      instance.
-        configuration-instances       Lists all instances associated with a
-                                      configuration group.
-        configuration-list            Lists all configuration groups.
-        configuration-parameter-list  Lists available parameters for a
-                                      configuration group.
-        configuration-parameter-show  Shows details of a configuration parameter.
-        configuration-patch           Patches a configuration group.
-        configuration-show            Shows details of a configuration group.
-        configuration-update          Updates a configuration group.
-        create                        Creates a new instance.
-        database-create               Creates a database on an instance.
-        database-delete               Deletes a database from an instance.
-        database-list                 Lists available databases on an instance.
-        datastore-list                Lists available datastores.
-        datastore-show                Shows details of a datastore.
-        datastore-version-list        Lists available versions for a datastore.
-        datastore-version-show        Shows details of a datastore version.
-        delete                        Deletes an instance.
-        detach-replica                Detaches a replica instance from its
-                                      replication source.
-        eject-replica-source          Ejects a replica source from its set.
-        execution-delete              Deletes an execution.
-        execution-list                Lists executions of a scheduled backup of an
-                                      instance.
-        flavor-list                   Lists available flavors.
-        flavor-show                   Shows details of a flavor.
-        force-delete                  Force delete an instance.
-        limit-list                    Lists the limits for a tenant.
-        list                          Lists all the instances.
-        log-disable                   Instructs Trove guest to stop collecting log
-                                      details.
-        log-discard                   Instructs Trove guest to discard the
-                                      container of the published log.
-        log-enable                    Instructs Trove guest to start collecting
-                                      log details.
-        log-list                      Lists the log files available for instance.
-        log-publish                   Instructs Trove guest to publish latest log
-                                      entries on instance.
-        log-save                      Save log file for instance.
-        log-show                      Instructs Trove guest to show details of
-                                      log.
-        log-tail                      Display log entries for instance.
-        metadata-create               Creates metadata in the database for
-                                      instance <id>.
-        metadata-delete               Deletes metadata for instance <id>.
-        metadata-edit                 Replaces metadata value with a new one, this
-                                      is non-destructive.
-        metadata-list                 Shows all metadata for instance <id>.
-        metadata-show                 Shows metadata entry for key <key> and
-                                      instance <id>.
-        metadata-update               Updates metadata, this is destructive.
-        module-apply                  Apply modules to an instance.
-        module-create                 Create a module.
-        module-delete                 Delete a module.
-        module-instances              Lists the instances that have a particular
-                                      module applied.
-        module-list                   Lists the modules available.
-        module-list-instance          Lists the modules that have been applied to
-                                      an instance.
-        module-query                  Query the status of the modules on an
-                                      instance.
-        module-remove                 Remove a module from an instance.
-        module-retrieve               Retrieve module contents from an instance.
-        module-show                   Shows details of a module.
-        module-update                 Update a module.
-        promote-to-replica-source     Promotes a replica to be the new replica
-                                      source of its set.
-        quota-show                    Show quotas for a tenant.
-        quota-update                  Update quotas for a tenant.
-        reset-status                  Set the status to NONE.
-        resize-instance               Resizes an instance with a new flavor.
-        resize-volume                 Resizes the volume size of an instance.
-        restart                       Restarts an instance.
-        root-disable                  Disables root for an instance.
-        root-enable                   Enables root for an instance and resets if
-                                      already exists.
-        root-show                     Gets status if root was ever enabled for an
-                                      instance or cluster.
-        schedule-create               Schedules backups for an instance.
-        schedule-delete               Deletes a schedule.
-        schedule-list                 Lists scheduled backups for an instance.
-        schedule-show                 Shows details of a schedule.
-        secgroup-add-rule             Creates a security group rule.
-        secgroup-delete-rule          Deletes a security group rule.
-        secgroup-list                 Lists all security groups.
-        secgroup-list-rules           Lists all rules for a security group.
-        secgroup-show                 Shows details of a security group.
-        show                          Shows details of an instance.
-        update                        Updates an instance: Edits name,
-                                      configuration, or replica source.
-        upgrade                       Upgrades an instance to a new datastore
-                                      version.
-        user-create                   Creates a user on an instance.
-        user-delete                   Deletes a user from an instance.
-        user-grant-access             Grants access to a database(s) for a user.
-        user-list                     Lists the users for an instance.
-        user-revoke-access            Revokes access to a database for a user.
-        user-show                     Shows details of a user of an instance.
-        user-show-access              Shows access details of a user of an
-                                      instance.
-        user-update-attributes        Updates a user's attributes on an instance.
-        bash-completion               Prints arguments for bash_completion.
-        help                          Displays help about this program or one of
-                                      its subcommands.
-
-    Optional arguments:
-      --version                       Show program's version number and exit.
-      --debug                         Print debugging output.
-      --service-type <service-type>   Defaults to database for most actions.
-      --service-name <service-name>   Defaults to env[TROVE_SERVICE_NAME].
-      --bypass-url <bypass-url>       Defaults to env[TROVE_BYPASS_URL].
-      --database-service-name <database-service-name>
-                                      Defaults to
-                                      env[TROVE_DATABASE_SERVICE_NAME].
-      --endpoint-type <endpoint-type>
-                                      Defaults to env[TROVE_ENDPOINT_TYPE] or
-                                      env[OS_ENDPOINT_TYPE] or publicURL.
-      --os-database-api-version <database-api-ver>
-                                      Accepts 1, defaults to
-                                      env[OS_DATABASE_API_VERSION].
-      --retries <retries>             Number of retries.
-      --json, --os-json-output        Output JSON instead of prettyprint. Defaults
-                                      to env[OS_JSON_OUTPUT].
-      --profile HMAC_KEY              HMAC key used to encrypt context data when
-                                      profiling the performance of an operation.
-                                      This key should be set to one of the HMAC
-                                      keys configured in Trove (they are found in
-                                      api-paste.ini, typically in /etc/trove).
-                                      Without the key, profiling will not be
-                                      triggered even if it is enabled on the
-                                      server side. Defaults to
-                                      env[OS_PROFILE_HMACKEY].
-      --os-auth-type <name>, --os-auth-plugin <name>
-                                      Authentication type to use
-      --os-region-name <region-name>  Specify the region to use. Defaults to
-                                      env[OS_REGION_NAME].
-
-    API Connection Options:
-      Options controlling the HTTP API Connections
-
-      --insecure                      Explicitly allow client to perform
-                                      "insecure" TLS (https) requests. The
-                                      server's certificate will not be verified
-                                      against any certificate authorities. This
-                                      option should be used with caution.
-      --os-cacert <ca-certificate>    Specify a CA bundle file to use in verifying
-                                      a TLS (https) server certificate. Defaults
-                                      to env[OS_CACERT].
-      --os-cert <certificate>         Defaults to env[OS_CERT].
-      --os-key <key>                  Defaults to env[OS_KEY].
-      --timeout <seconds>             Set request timeout (in seconds).
-
-    Authentication Options:
-      Options specific to the password plugin.
-
-      --os-auth-url OS_AUTH_URL       Authentication URL
-      --os-domain-id OS_DOMAIN_ID     Domain ID to scope to
-      --os-domain-name OS_DOMAIN_NAME
-                                      Domain name to scope to
-      --os-project-id OS_PROJECT_ID, --os-tenant-id OS_PROJECT_ID
-                                      Project ID to scope to
-      --os-project-name OS_PROJECT_NAME, --os-tenant-name OS_PROJECT_NAME
-                                      Project name to scope to
-      --os-project-domain-id OS_PROJECT_DOMAIN_ID
-                                      Domain ID containing project
-      --os-project-domain-name OS_PROJECT_DOMAIN_NAME
-                                      Domain name containing project
-      --os-trust-id OS_TRUST_ID       Trust ID
-      --os-default-domain-id OS_DEFAULT_DOMAIN_ID
-                                      Optional domain ID to use with v3 and v2
-                                      parameters. It will be used for both the
-                                      user and project domain in v3 and ignored in
-                                      v2 authentication.
-      --os-default-domain-name OS_DEFAULT_DOMAIN_NAME
-                                      Optional domain name to use with v3 API and
-                                      v2 parameters. It will be used for both the
-                                      user and project domain in v3 and ignored in
-                                      v2 authentication.
-      --os-user-id OS_USER_ID         User id
-      --os-username OS_USERNAME, --os-user-name OS_USERNAME
-                                      Username
-      --os-user-domain-id OS_USER_DOMAIN_ID
-                                      User's domain id
-      --os-user-domain-name OS_USER_DOMAIN_NAME
-                                      User's domain name
-      --os-password OS_PASSWORD       User's password
-    
-    See "trove help COMMAND" for help on a specific command.
-
-
-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()
-    [...]
-
-* Documentation: http://docs.openstack.org/developer/python-troveclient/
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
diff --git a/setup.cfg b/setup.cfg
index 73432d5..fefbda5 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -45,9 +45,16 @@ openstack.database.v1 =
 all_files = 1
 source-dir = doc/source
 build-dir = doc/build
+#warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html
 
 [wheel]
 universal = 1
+
+[pbr]
+autodoc_index_modules = True
+api_doc_dir = reference/api
+autodoc_exclude_modules =
+  troveclient.tests.*