diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 0000000..e75b8c3 --- /dev/null +++ b/doc/source/cli/index.rst @@ -0,0 +1,31 @@ +============================= + Command-line Tool Reference +============================= + +In order to use the CLI, you must provide your OpenStack username, +password, tenant, and auth endpoint. Use the corresponding +configuration options (``--os-username``, ``--os-password``, +``--os-tenant-id``, and ``--os-auth-url``) or set them in environment +variables:: + + export OS_USERNAME=user + export OS_PASSWORD=pass + export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b + export OS_AUTH_URL=http://auth.example.com:5000/v2.0 + +The command line tool will attempt to reauthenticate using your +provided credentials for every request. You can override this behavior +by manually supplying an auth token using ``--os-watcher-url`` and +``--os-auth-token``. You can alternatively set these environment +variables:: + + export OS_WATCHER_URL=http://watcher.example.org:9322/ + export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155 + +Once you've configured your authentication parameters, you can run +``watcher help`` to see a complete listing of available commands. + +.. toctree:: + + watcher + openstack_cli diff --git a/doc/source/openstack_cli.rst b/doc/source/cli/openstack_cli.rst similarity index 100% rename from doc/source/openstack_cli.rst rename to doc/source/cli/openstack_cli.rst diff --git a/doc/source/cli.rst b/doc/source/cli/watcher.rst similarity index 100% rename from doc/source/cli.rst rename to doc/source/cli/watcher.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index c494422..ae3182d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,42 +1,15 @@ Python bindings to the OpenStack Watcher API ============================================ -This is a client for OpenStack Watcher API. There's :doc:`a Python API -` (the :mod:`watcherclient` modules), and a :doc:`command-line script -` (installed as :program:`watcher`). Each implements the entire +This is a client for OpenStack Watcher API. There's a Python API +(the :mod:`watcherclient` modules), and a command-line script +(installed as :program:`watcher`). Each implements the entire OpenStack Watcher API. -You'll need credentials for an OpenStack cloud in order to use the watcher client. - - -Contents: - .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + cli/index + reference/index installation - api_v1 - cli - openstack_cli contributing - -Contributing -============ - -Code is hosted at `git.openstack.org`_. Submit bugs to the Watcher project on -`Launchpad`_. Submit code to the openstack/python-watcherclient project using -`Gerrit`_. - -.. _git.openstack.org: https://git.openstack.org/cgit/openstack/python-watcherclient -.. _Launchpad: https://launchpad.net/watcher -.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow - -Testing -------- - -The preferred way to run the unit tests is using ``tox``. - -See `Consistent Testing Interface`_ for more details. - -.. _Consistent Testing Interface: http://git.openstack.org/cgit/openstack/governance/tree/reference/project-testing-interface.rst -.. _Watcher: https://wiki.openstack.org/wiki/Watcher diff --git a/doc/source/reference/api/index.rst b/doc/source/reference/api/index.rst new file mode 100644 index 0000000..df916b6 --- /dev/null +++ b/doc/source/reference/api/index.rst @@ -0,0 +1,8 @@ +====================== + Python API Reference +====================== + +.. toctree:: + :maxdepth: 2 + + autoindex diff --git a/doc/source/api_v1.rst b/doc/source/reference/api_v1.rst similarity index 98% rename from doc/source/api_v1.rst rename to doc/source/reference/api_v1.rst index fa0ac92..911623b 100644 --- a/doc/source/api_v1.rst +++ b/doc/source/reference/api_v1.rst @@ -80,12 +80,6 @@ Refer to the modules themselves, for more details. watcherclient Modules ===================== -.. toctree:: - :maxdepth: 1 - - modules - - .. _watcherclient.v1.audit: api/watcherclient.v1.audit.html#watcherclient.v1.audit.Audit .. _watcherclient.v1.client.Client: api/watcherclient.v1.client.html#watcherclient.v1.client.Client .. _Client: api/watcherclient.v1.client.html#watcherclient.v1.client.Client diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst new file mode 100644 index 0000000..c0d4082 --- /dev/null +++ b/doc/source/reference/index.rst @@ -0,0 +1,14 @@ +========================== + Python Library Reference +========================== + +In order to use the python api directly, you must first obtain an auth +token and identify which endpoint you wish to speak to. Once you have +done so, you can use the API like so. + + +.. toctree:: + :maxdepth: 2 + + api/index + api_v1 diff --git a/setup.cfg b/setup.cfg index 2e0c867..651f6c1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -104,6 +104,9 @@ watcherclient.v1 = [pbr] autodoc_index_modules = True +autodoc_exclude_modules = + glanceclient.tests.* +api_doc_dir = reference/api [build_sphinx] source-dir = doc/source