Update Watcher CLI documentation

I updated, in this patchset, some examples of wacher CLI, because option format has changed (we have no more '-' character in keywords) I added a new page for the openstack client + our watcher plugin. Change-Id: Ia2ae148e4357eb64c8e3df1f3036dc992e85714c
2016-05-24 15:19:31 +02:00 · 2016-05-24 15:19:31 +02:00 · 89cfc55870
parent 4c19084cb1
commit 89cfc55870
7 changed files with 144 additions and 32 deletions
--- a/.gitignore
+++ b/.gitignore
@ -42,6 +42,7 @@ output/*/index.html

 # Sphinx
 doc/build
+doc/source/api

 # pbr generates these
 AUTHORS
--- a/README.rst
+++ b/README.rst
@ -49,9 +49,17 @@ You can install the Watcher CLI with the following command:

 .. code::

-   pip install python-watcherclient
+   sudo pip install python-watcherclient


+You can also use the `OpenStack client <http://docs.openstack.org/cli-reference/overview.html>`_
+with Watcher (our watcher plugin for OpenStack client is included in the
+python-watcherclient package). To install it, you have just to run this command:
+
+.. code::
+
+   sudo pip install python-openstackclient
+
 Configuration
 =============

@ -73,31 +81,48 @@ Source these credentials into your current shell session:

   # source creds

-You should be able to launch the following command which gets the list of previously created Audit Templates:
+You should be able to launch the following command which gets the list of
+previously created Audit Templates:

 .. code::

-   # watcher audit-template-list
-   +------+------+
-   | UUID | Name |
-   +------+------+
-   +------+------+
+   # watcher audittemplate list

-You can view the entire list of available Watcher commands and options using this command:
+or::
+
+   # openstack optimize audittemplate list
+   +--------------------------------+------+----------------------+----------+
+   | UUID                           | Name | Goal                 | Strategy |
+   +--------------------------------+------+----------------------+----------+
+   +--------------------------------+------+----------------------+----------+
+
+
+You can view the entire list of available Watcher commands and options using
+this command:

 .. code::

   # watcher help

+or::
+
+   # openstack help optimize
+

 Troubleshootings
 ================

-If any watcher command fails, you can obtain more details with the **--debug** option :
+If any watcher command fails, you can obtain more details with the **--debug**
+option :

 .. code::

-   # watcher --debug audit-template-list
+   # watcher --debug audittemplate list
+
+or::
+
+   # openstack --debug optimize audittemplate list
+

 Install the openstack CLI :

@ -105,7 +130,8 @@ Install the openstack CLI :

   # pip install python-openstackclient

-Make sure that your OpenStack credentials are correct. If so, you should be able to verify that the watcher user has been declared in your OpenStack keystone :
+Make sure that your Openstack credentials are correct. If so, you should be able
+to verify that the watcher user has been declared in your Openstack keystone :

 .. code::

--- a/doc/source/api/autoindex.rst
+++ b/doc/source/api/autoindex.rst
@ -1,23 +1,25 @@
 .. toctree::
   :maxdepth: 1

+   watcherclient._i18n.rst
   watcherclient.client.rst
   watcherclient.common.apiclient.base.rst
   watcherclient.common.apiclient.exceptions.rst
   watcherclient.common.base.rst
   watcherclient.common.cliutils.rst
+   watcherclient.common.command.rst
   watcherclient.common.http.rst
-   watcherclient.common.i18n.rst
   watcherclient.common.utils.rst
   watcherclient.exceptions.rst
+   watcherclient.plugin.rst
   watcherclient.shell.rst
   watcherclient.tests.keystone_client_fixtures.rst
   watcherclient.tests.test_client.rst
   watcherclient.tests.test_http.rst
   watcherclient.tests.test_import.rst
-   watcherclient.tests.test_shell.rst
   watcherclient.tests.test_utils.rst
   watcherclient.tests.utils.rst
+   watcherclient.tests.v1.base.rst
   watcherclient.tests.v1.test_action.rst
   watcherclient.tests.v1.test_action_plan.rst
   watcherclient.tests.v1.test_action_plan_shell.rst
@ -29,7 +31,8 @@
   watcherclient.tests.v1.test_goal.rst
   watcherclient.tests.v1.test_goal_shell.rst
   watcherclient.tests.v1.test_metric_collector.rst
-   watcherclient.tests.v1.test_metric_collector_shell.rst
+   watcherclient.tests.v1.test_strategy.rst
+   watcherclient.tests.v1.test_strategy_shell.rst
   watcherclient.v1.action.rst
   watcherclient.v1.action_plan.rst
   watcherclient.v1.action_plan_shell.rst
@ -42,7 +45,7 @@
   watcherclient.v1.goal.rst
   watcherclient.v1.goal_shell.rst
   watcherclient.v1.metric_collector.rst
-   watcherclient.v1.metric_collector_shell.rst
   watcherclient.v1.resource_fields.rst
-   watcherclient.v1.shell.rst
+   watcherclient.v1.strategy.rst
+   watcherclient.v1.strategy_shell.rst
   watcherclient.version.rst
--- a/doc/source/cli.rst
+++ b/doc/source/cli.rst
@ -19,7 +19,7 @@ DESCRIPTION
 ===========

 The :program:`watcher` command-line interface (CLI) interacts with the
-OpenStack TODEFINE Service (Watcher).
+OpenStack infra-optim Service (Watcher).

 In order to use the CLI, you must provide your OpenStack username, password,
 project (historically called tenant), and auth endpoint. You can use
@ -28,26 +28,26 @@ configuration options :option:`--os-username`, :option:`--os-password`,
 and :option:`--os-auth-url`, or set the corresponding
 environment variables::

-    export OS_USERNAME=user
-    export OS_PASSWORD=password
-    export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b   # or OS_TENANT_NAME
-    export OS_TENANT_NAME=project                          # or OS_TENANT_ID
-    export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b   # or OS_TENANT_NAME
+    $ export OS_TENANT_NAME=project                          # or OS_TENANT_ID
+    $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0

 The command-line tool will attempt to reauthenticate using the provided
 credentials for every request. You can override this behavior by manually
 supplying an auth token using :option:`--watcher-url` and
 :option:`--os-auth-token`, or by setting the corresponding environment variables::

-    export WATCHER_URL=http://watcher.example.org:9322/
-    export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+    $ export WATCHER_URL=http://watcher.example.org:9322/
+    $ export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155

 Since Keystone can return multiple regions in the Service Catalog, you can
 specify the one you want with :option:`--os-region-name` or set the following
 environment variable. (It defaults to the first in the list returned.)
 ::

-    export OS_REGION_NAME=region
+    $ export OS_REGION_NAME=region

 Watcher CLI supports bash completion. The command-line tool can automatically
 fill partially typed commands. To use this feature, source the below file
@ -55,7 +55,7 @@ fill partially typed commands. To use this feature, source the below file
 https://git.openstack.org/cgit/openstack/python-watcherclient/tree/tools/watcher.bash_completion)
 to your terminal and then bash completion should work::

-    source watcher.bash_completion
+    $ source watcher.bash_completion

 To avoid doing this every time, add this to your ``.bashrc`` or copy the
 watcher.bash_completion file to the default bash completion scripts directory
@ -66,11 +66,11 @@ OPTIONS

 To get a list of available (sub)commands and options, run::

-    watcher help
+    $ watcher help

 To get usage and options of a command, run::

-    watcher help <command>
+    $ watcher help <command>


 EXAMPLES
@ -78,12 +78,12 @@ EXAMPLES

 Get information about the audit-create command::

-    watcher help audit-create
+    $ watcher help audit create

 Get a list of available goal::

-    watcher goal-list
+    $ watcher goal list

 Get a list of audits::

-    watcher audit-list
+    $ watcher audit list
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@ -18,6 +18,7 @@ Contents:
   installation
   api_v1
   cli
+   openstack_cli
   contributing

 Contributing
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@ -2,7 +2,7 @@
 Installation
 ============

-Or, if you have `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_   installed::
+If you have `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_   installed::

    $ mkvirtualenv python-watcherclient
    $ git clone https://git.openstack.org/openstack/python-watcherclient
--- a/doc/source/openstack_cli.rst
+++ b/doc/source/openstack_cli.rst
@ -0,0 +1,81 @@
+=====================================================================
+:program:`openstack` Command-Line Interface (CLI) with Watcher plugin
+=====================================================================
+
+.. program:: openstack
+.. highlight:: bash
+
+SYNOPSIS
+========
+
+:program:`openstack` [options] :program:`optimize` <command> [command-options]
+
+:program:`openstack help optimize`
+
+:program:`openstack help optimize` <command>
+
+
+DESCRIPTION
+===========
+
+The :program:`openstack` command-line interface (CLI) can interact with the
+OpenStack infra-optim Service (Watcher), by using our additional plugin
+(included into the python-watcherclient package).
+
+In order to use the CLI, you must provide your OpenStack username, password,
+project (historically called tenant), and auth endpoint. You can use
+configuration options :option:`--os-username`, :option:`--os-password`,
+:option:`--os-tenant-id` (or :option:`--os-tenant-name`),
+and :option:`--os-auth-url`, or set the corresponding
+environment variables::
+
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_TENANT_ID=b363706f891f48019483f8bd6503c54b   # or OS_TENANT_NAME
+    $ export OS_TENANT_NAME=project                          # or OS_TENANT_ID
+    $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+The command-line tool will attempt to reauthenticate using the provided
+credentials for every request. You can override this behavior by manually
+supplying an auth token using :option:`--watcher-url` and
+:option:`--os-auth-token`, or by setting the corresponding environment variables::
+
+    export WATCHER_URL=http://watcher.example.org:9322/
+    export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+
+Since Keystone can return multiple regions in the Service Catalog, you can
+specify the one you want with :option:`--os-region-name` or set the following
+environment variable. (It defaults to the first in the list returned.)
+::
+
+    $ export OS_REGION_NAME=region
+
+OPTIONS
+=======
+
+To get a list of available (sub)commands and options, run::
+
+    $ openstack help optimize
+
+To get usage and options of a command, run::
+
+    $ openstack help optimize <command>
+
+
+EXAMPLES
+========
+
+Get information about the audit-create command::
+
+    $ openstack help optimize audit create
+
+
+Get a list of available goal::
+
+    $ openstack optimize goal list
+
+
+Get a list of audits::
+
+    $ openstack optimize audit list
+