From 0d5c899edb6baa745147207d99b45cd073803f23 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 29 Jun 2017 16:48:58 -0400 Subject: [PATCH] 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 --- .gitignore | 2 + README.rst | 308 +------------------------ doc/source/conf.py | 39 ---- doc/source/index.rst | 4 +- doc/source/reference/index.rst | 8 + doc/source/{usage.rst => user/api.rst} | 0 doc/source/user/index.rst | 62 +++++ setup.cfg | 7 + 8 files changed, 85 insertions(+), 345 deletions(-) create mode 100644 doc/source/reference/index.rst rename doc/source/{usage.rst => user/api.rst} (100%) create mode 100644 doc/source/user/index.rst diff --git a/.gitignore b/.gitignore index 7dfa5c32..9f6cf165 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 2ba58bc7..b407d21f 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-name ] [--bypass-url ] - [--database-service-name ] - [--endpoint-type ] - [--os-database-api-version ] - [--retries ] [--json] [--profile HMAC_KEY] [--insecure] - [--os-cacert ] [--os-cert ] - [--os-key ] [--timeout ] [--os-auth-type ] - [--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 ] - ... - - Command-line interface to the OpenStack Trove API. - - Positional arguments: - - 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 . - metadata-delete Deletes metadata for instance . - metadata-edit Replaces metadata value with a new one, this - is non-destructive. - metadata-list Shows all metadata for instance . - metadata-show Shows metadata entry for key and - instance . - 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 Defaults to database for most actions. - --service-name Defaults to env[TROVE_SERVICE_NAME]. - --bypass-url Defaults to env[TROVE_BYPASS_URL]. - --database-service-name - Defaults to - env[TROVE_DATABASE_SERVICE_NAME]. - --endpoint-type - Defaults to env[TROVE_ENDPOINT_TYPE] or - env[OS_ENDPOINT_TYPE] or publicURL. - --os-database-api-version - Accepts 1, defaults to - env[OS_DATABASE_API_VERSION]. - --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 , --os-auth-plugin - Authentication type to use - --os-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 Specify a CA bundle file to use in verifying - a TLS (https) server certificate. Defaults - to env[OS_CACERT]. - --os-cert Defaults to env[OS_CERT]. - --os-key Defaults to env[OS_KEY]. - --timeout 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 c342ce9c..09867dc6 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 038e4066..392e5c94 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 00000000..1d9e914d --- /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 similarity index 100% rename from doc/source/usage.rst rename to doc/source/user/api.rst diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 00000000..2656e425 --- /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 73432d5f..fefbda55 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.*