openstack/python-troveclient
Code Issues Proposed changes

rearrange docs into new standard layout

Browse Source 
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>
This commit is contained in:
Doug Hellmann
2017-06-29 16:48:58 -04:00
parent 8aaa4e81aa
commit 0d5c899edb
8 changed files with 85 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -14,3 +14,5 @@ ChangeLog
# Files created by releasenotes build # Files created by releasenotes build
releasenotes/build releasenotes/build
/doc/build/
/doc/source/reference/api/

308
README.rst
View File

@@ -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 ``troveclient`` module), and a command-line script (``trove``). Each
implements 100% of the OpenStack Trove API. 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 command-line tool. You may also want to look at the
`OpenStack API documentation`_. `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. python-troveclient is licensed under the Apache License like the rest of OpenStack.
* License: Apache License, Version 2.0 * License: Apache License, Version 2.0
* `PyPi`_ - package installation * Documentation: http://docs.openstack.org/developer/python-troveclient/
* `Online Documentation`_ * Bugs: https://bugs.launchpad.net/python-troveclient
* `PyPi`_- package installation
* `Blueprints`_ - feature specifications * `Blueprints`_ - feature specifications
* `Bugs`_ - issue tracking
* `Git Source`_ * `Git Source`_
* `Github`_ * `Github`_
* `Specs`_ * `Specs`_
* `How to Contribute`_ * `How to Contribute`_
.. _PyPi: https://pypi.python.org/pypi/python-troveclient .. _PyPi: https://pypi.python.org/pypi/python-troveclient
.. _Online Documentation: http://docs.openstack.org/developer/python-troveclient
.. _Blueprints: https://blueprints.launchpad.net/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 .. _Git Source: https://git.openstack.org/cgit/openstack/python-troveclient
.. _Github: https://github.com/openstack/python-troveclient .. _Github: https://github.com/openstack/python-troveclient
.. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html .. _How to Contribute: http://docs.openstack.org/infra/manual/developers.html
.. _Specs: http://specs.openstack.org/openstack/trove-specs/ .. _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/

39
doc/source/conf.py
View File

@@ -27,45 +27,6 @@ ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
sys.path.insert(0, ROOT) sys.path.insert(0, ROOT)
sys.path.insert(0, BASE_DIR) 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 = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.doctest', 'sphinx.ext.doctest',

4
doc/source/index.rst
View File

@@ -18,8 +18,8 @@
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
usage user/index
ref/v1/index reference/index
Indices and tables Indices and tables
================== ==================

8
doc/source/reference/index.rst Normal file
View File

@@ -0,0 +1,8 @@
=============================
troveclient Reference Guide
=============================
.. toctree::
:maxdepth: 2
api/autoindex

0
doc/source/usage.rst → doc/source/user/api.rst
View File

62
doc/source/user/index.rst Normal file
View File

@@ -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

7
setup.cfg
View File

@@ -45,9 +45,16 @@ openstack.database.v1 =
all_files = 1 all_files = 1
source-dir = doc/source source-dir = doc/source
build-dir = doc/build build-dir = doc/build
#warning-is-error = 1
[upload_sphinx] [upload_sphinx]
upload-dir = doc/build/html upload-dir = doc/build/html
[wheel] [wheel]
universal = 1 universal = 1
[pbr]
autodoc_index_modules = True
api_doc_dir = reference/api
autodoc_exclude_modules =
troveclient.tests.*