From 0d5c899edb6baa745147207d99b45cd073803f23 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 29 Jun 2017 16:48:58 -0400 Subject: 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 --- doc/source/conf.py | 39 ------------ doc/source/index.rst | 4 +- doc/source/reference/index.rst | 8 +++ doc/source/usage.rst | 135 ----------------------------------------- doc/source/user/api.rst | 135 +++++++++++++++++++++++++++++++++++++++++ doc/source/user/index.rst | 62 +++++++++++++++++++ 6 files changed, 207 insertions(+), 176 deletions(-) create mode 100644 doc/source/reference/index.rst delete mode 100644 doc/source/usage.rst create mode 100644 doc/source/user/api.rst create mode 100644 doc/source/user/index.rst (limited to 'doc') 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/usage.rst deleted file mode 100644 index 374d155..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,135 +0,0 @@ -Using the Client Programmatically -================================= - -Authentication --------------- - -Authenticating is necessary to use every feature of the client. - -To create the client, create an instance of the Client class. -The auth url, username, password, and project name must be specified in the -call to the constructor. - -.. testcode:: - - from troveclient.v1 import client - tc = client.Client(username="testuser", - password="PASSWORD", - project_id="test_project", - region_name="EAST", - auth_url="http://api-server:5000/v2.0") - -The default authentication strategy assumes a keystone compliant auth system. - -Once you have an authenticated client object you can make calls with it, -for example: - -.. testcode:: - - flavors = tc.flavors.list() - datastores = tc.datastores.list() - -Instances ---------- - -The following example creates a 512 MB instance with a 1 GB volume: - -.. testcode:: - - from troveclient.v1 import client - tc = client.Client(username="testuser", - password="PASSWORD", - project_id="test_project", - region_name="EAST", - auth_url="http://api-server:5000/v2.0") - - flavor_id = '1' - volume = {'size':1} - databases = [{"name": "my_db", - "character_set": "latin2", # These two fields - "collate": "latin2_general_ci"}] # are optional. - datastore = 'mysql' - datastore_version = '5.6-104' - users = [{"name": "jsmith", "password": "12345", - "databases": [{"name": "my_db"}] - }] - instance = client.instances.create("My Instance", flavor_id, volume, - databases, users, datastore=datastore, - datastore_version=datastore_version) - -To retrieve the instance, use the "get" method of "instances": - -.. testcode:: - - updated_instance = client.instances.get(instance.id) - print(updated_instance.name) - print(" Status=%s Flavor=%s" % - (updated_instance.status, updated_instance.flavor['id'])) - -.. testoutput:: - - My Instance - Status=BUILD Flavor=1 - -You can delete an instance by calling "delete" on the instance object itself, -or by using the delete method on "instances." - -.. testcode:: - - # Wait for the instance to be ready before we delete it. - import time - from troveclient.exceptions import NotFound - - while instance.status == "BUILD": - instance.get() - time.sleep(1) - print("Ready in an %s state." % instance.status) - instance.delete() - # Delete and wait for the instance to go away. - while True: - try: - instance = client.instances.get(instance.id) - assert instance.status == "SHUTDOWN" - except NotFound: - break - -.. testoutput:: - - Ready in an ACTIVE state. - - -Listing Items and Pagination --------------------------------- - -Lists paginate after twenty items, meaning you'll only get twenty items back -even if there are more. To see the next set of items, send a marker. The marker -is a key value (in the case of instances, the ID) which is the non-inclusive -starting point for all returned items. - -The lists returned by the client always include a "next" property. This -can be used as the "marker" argument to get the next section of the list -back from the server. If no more items are available, then the next property -is None. - -Pagination applies to all listed objects, like instances, datastores, etc. -The example below is for instances. - -.. testcode:: - - # There are currently 30 instances. - - instances = client.instances.list() - print(len(instances)) - print(instances.next is None) - - instances2 = client.instances.list(marker=instances.next) - print(len(instances2)) - print(instances2.next is None) - -.. testoutput:: - - 20 - False - 10 - True - diff --git a/doc/source/user/api.rst b/doc/source/user/api.rst new file mode 100644 index 0000000..374d155 --- /dev/null +++ b/doc/source/user/api.rst @@ -0,0 +1,135 @@ +Using the Client Programmatically +================================= + +Authentication +-------------- + +Authenticating is necessary to use every feature of the client. + +To create the client, create an instance of the Client class. +The auth url, username, password, and project name must be specified in the +call to the constructor. + +.. testcode:: + + from troveclient.v1 import client + tc = client.Client(username="testuser", + password="PASSWORD", + project_id="test_project", + region_name="EAST", + auth_url="http://api-server:5000/v2.0") + +The default authentication strategy assumes a keystone compliant auth system. + +Once you have an authenticated client object you can make calls with it, +for example: + +.. testcode:: + + flavors = tc.flavors.list() + datastores = tc.datastores.list() + +Instances +--------- + +The following example creates a 512 MB instance with a 1 GB volume: + +.. testcode:: + + from troveclient.v1 import client + tc = client.Client(username="testuser", + password="PASSWORD", + project_id="test_project", + region_name="EAST", + auth_url="http://api-server:5000/v2.0") + + flavor_id = '1' + volume = {'size':1} + databases = [{"name": "my_db", + "character_set": "latin2", # These two fields + "collate": "latin2_general_ci"}] # are optional. + datastore = 'mysql' + datastore_version = '5.6-104' + users = [{"name": "jsmith", "password": "12345", + "databases": [{"name": "my_db"}] + }] + instance = client.instances.create("My Instance", flavor_id, volume, + databases, users, datastore=datastore, + datastore_version=datastore_version) + +To retrieve the instance, use the "get" method of "instances": + +.. testcode:: + + updated_instance = client.instances.get(instance.id) + print(updated_instance.name) + print(" Status=%s Flavor=%s" % + (updated_instance.status, updated_instance.flavor['id'])) + +.. testoutput:: + + My Instance + Status=BUILD Flavor=1 + +You can delete an instance by calling "delete" on the instance object itself, +or by using the delete method on "instances." + +.. testcode:: + + # Wait for the instance to be ready before we delete it. + import time + from troveclient.exceptions import NotFound + + while instance.status == "BUILD": + instance.get() + time.sleep(1) + print("Ready in an %s state." % instance.status) + instance.delete() + # Delete and wait for the instance to go away. + while True: + try: + instance = client.instances.get(instance.id) + assert instance.status == "SHUTDOWN" + except NotFound: + break + +.. testoutput:: + + Ready in an ACTIVE state. + + +Listing Items and Pagination +-------------------------------- + +Lists paginate after twenty items, meaning you'll only get twenty items back +even if there are more. To see the next set of items, send a marker. The marker +is a key value (in the case of instances, the ID) which is the non-inclusive +starting point for all returned items. + +The lists returned by the client always include a "next" property. This +can be used as the "marker" argument to get the next section of the list +back from the server. If no more items are available, then the next property +is None. + +Pagination applies to all listed objects, like instances, datastores, etc. +The example below is for instances. + +.. testcode:: + + # There are currently 30 instances. + + instances = client.instances.list() + print(len(instances)) + print(instances.next is None) + + instances2 = client.instances.list(marker=instances.next) + print(len(instances2)) + print(instances2.next is None) + +.. testoutput:: + + 20 + False + 10 + True + 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 -- cgit v1.2.1