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>
This commit is contained in:
parent
8aaa4e81aa
commit
0d5c899edb
|
@ -14,3 +14,5 @@ ChangeLog
|
|||
|
||||
# Files created by releasenotes build
|
||||
releasenotes/build
|
||||
/doc/build/
|
||||
/doc/source/reference/api/
|
||||
|
|
308
README.rst
308
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/
|
||||
|
|
|
@ -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',
|
||||
|
|
|
@ -18,8 +18,8 @@
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
usage
|
||||
ref/v1/index
|
||||
user/index
|
||||
reference/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
|
@ -0,0 +1,8 @@
|
|||
=============================
|
||||
troveclient Reference Guide
|
||||
=============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api/autoindex
|
|
@ -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
|
|
@ -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.*
|
||||
|
|
Loading…
Reference in New Issue