Update Watcher documentation

We introduced a new watcher plugin for OpenStack CLI. This patchset
updates accordingly the watcher documentation and schemas.

Partially Implements: blueprint openstackclient-plugin

Change-Id: Ib00469c8645fff21f5ba95951379827dbd359c69

doc/source/deploy/user-guide.rst

@@ -32,17 +32,17 @@ This guide assumes you have a working installation of Watcher. If you get
 Please refer to the `installation guide`_.
 In order to use Watcher, you have to configure your credentials suitable for
 watcher command-line tools.
-If you need help on a specific command, you can use:
 
-.. code:: bash
+You can interact with Watcher either by using our dedicated `Watcher CLI`_
-
+named ``watcher``, or by using the `OpenStack CLI`_ ``openstack``.
-  $ watcher help COMMAND
 
 If you want to deploy Watcher in Horizon, please refer to the `Watcher Horizon
 plugin installation guide`_.
 
 .. _`installation guide`: https://factory.b-com.com/www/watcher/doc/python-watcherclient
 .. _`Watcher Horizon plugin installation guide`: https://factory.b-com.com/www/watcher/doc/watcher-dashboard/deploy/installation.html
+.. _`OpenStack CLI`: http://docs.openstack.org/developer/python-openstackclient/man/openstack.html
+.. _`Watcher CLI`: https://factory.b-com.com/www/watcher/doc/python-watcherclient/index.html
 
 Seeing what the Watcher CLI can do ?
 ------------------------------------
@@ -51,7 +51,11 @@ watcher binary without options.
 
 .. code:: bash
 
-  $ watcher
+  $ watcher help
+
+or::
+
+  $ openstack help optimize
 
 How do I run an audit of my cluster ?
 -------------------------------------
@@ -60,7 +64,11 @@ First, you need to find the :ref:`goal <goal_definition>` you want to achieve:
 
 .. code:: bash
 
-  $ watcher goal-list
+  $ watcher goal list
+
+or::
+
+  $ openstack optimize goal list
 
 .. note::
 
@@ -73,22 +81,36 @@ An :ref:`audit template <audit_template_definition>` defines an optimization
 
 .. code:: bash
 
-  $ watcher audit-template-create my_first_audit_template <your_goal_uuid>
+  $ watcher audittemplate create my_first_audit_template <your_goal>
+
+or::
+
+  $ openstack optimize audittemplate create my_first_audit_template <your_goal>
 
 Although optional, you may want to actually set a specific strategy for your
-audit template. If so, you may can search of its UUID using the following
+audit template. If so, you may can search of its UUID or name using the
-command:
+following command:
 
 .. code:: bash
 
-  $ watcher strategy-list --goal-uuid <your_goal_uuid>
+  $ watcher strategy list --goal-uuid <your_goal_uuid>
+
+or::
+
+  $ openstack optimize strategy list --goal-uuid <your_goal_uuid>
+
 
 The command to create your audit template would then be:
 
 .. code:: bash
 
-  $ watcher audit-template-create my_first_audit_template <your_goal_uuid> \
+  $ watcher audittemplate create my_first_audit_template <your_goal> \
-    --strategy-uuid <your_strategy_uuid>
+    --strategy <your_strategy>
+
+or::
+
+  $ openstack optimize audittemplate create my_first_audit_template <your_goal> \
+    --strategy <your_strategy>
 
 Then, you can create an audit. An audit is a request for optimizing your
 cluster depending on the specified :ref:`goal <goal_definition>`.
@@ -97,19 +119,26 @@ You can launch an audit on your cluster by referencing the
 :ref:`audit template <audit_template_definition>` (i.e. the settings of your
 audit) that you want to use.
 
-- Get the :ref:`audit template <audit_template_definition>` UUID:
+- Get the :ref:`audit template <audit_template_definition>` UUID or name:
 
 .. code:: bash
 
-  $ watcher audit-template-list
+  $ watcher audittemplate list
+
+or::
+
+  $ openstack optimize audittemplate list
 
 - Start an audit based on this :ref:`audit template
   <audit_template_definition>` settings:
 
 .. code:: bash
 
-  $ watcher audit-create -a <your_audit_template_uuid>
+  $ watcher audit create -a <your_audit_template>
 
+or::
+
+  $ openstack optimize audit create -a <your_audit_template>
 
 Watcher service will compute an :ref:`Action Plan <action_plan_definition>`
 composed of a list of potential optimization :ref:`actions <action_definition>`
@@ -123,15 +152,22 @@ configuration file.
 
 .. code:: bash
 
-  $ watcher action-plan-list --audit <the_audit_uuid>
+  $ watcher actionplan list --audit <the_audit_uuid>
+
+or::
+
+  $ openstack optimize actionplan list --audit <the_audit_uuid>
 
 - Have a look on the list of optimization :ref:`actions <action_definition>`
   contained in this new :ref:`action plan <action_plan_definition>`:
 
 .. code:: bash
 
-  $ watcher action-list --action-plan <the_action_plan_uuid>
+  $ watcher action list --action-plan <the_action_plan_uuid>
 
+or::
+
+  $ openstack optimize action list --action-plan <the_action_plan_uuid>
 
 Once you have learned how to create an :ref:`Action Plan
 <action_plan_definition>`, it's time to go further by applying it to your
@@ -141,18 +177,30 @@ cluster:
 
 .. code:: bash
 
-  $ watcher action-plan-start <the_action_plan_uuid>
+  $ watcher actionplan start <the_action_plan_uuid>
+
+or::
+
+  $ openstack optimize actionplan start <the_action_plan_uuid>
 
 You can follow the states of the :ref:`actions <action_definition>` by
 periodically calling:
 
 .. code:: bash
 
-  $ watcher action-list
+  $ watcher action list
+
+or::
+
+  $ openstack optimize action list
 
 You can also obtain more detailed information about a specific action:
 
 .. code:: bash
 
-  $ watcher action-show <the_action_uuid>
+  $ watcher action show <the_action_uuid>
+
+or::
+
+  $ openstack optimize action show <the_action_uuid>
 

doc/source/image_src/plantuml/README.rst

@@ -0,0 +1,14 @@
+plantuml
+========
+
+
+To build an image from a source file, you have to upload the plantuml JAR file
+available on  http://plantuml.com/download.html.
+After, just run this command to build your image:
+
+.. code-block:: shell
+
+    $ cd doc/source/images
+    $ java -jar /path/to/plantuml.jar doc/source/image_src/plantuml/my_image.txt
+    $ ls doc/source/images/
+    my_image.png

doc/source/image_src/plantuml/sequence_create_and_launch_audit.txt

@@ -3,7 +3,7 @@
 
 actor Administrator
 
-Administrator -> "Watcher CLI" : watcher audit-create -a <audit_template_uuid>
+Administrator -> "Watcher CLI" : watcher audit create -a <audit_template>
 
 "Watcher CLI" -> "Watcher API" : POST audit(parameters)
 "Watcher API" -> "Watcher Database" : create new audit in database (status=PENDING)
@@ -14,7 +14,7 @@ Administrator -> "Watcher CLI" : watcher audit-create -a <audit_template_uuid>
 Administrator <-- "Watcher CLI" : new audit uuid
 
 "Watcher API" -> "AMQP Bus" : trigger_audit(new_audit.uuid)
-"AMQP Bus" -> "Watcher Decision Engine" : trigger_audit(new_audit.uuid)
+"AMQP Bus" -> "Watcher Decision Engine" : trigger_audit(new_audit.uuid) (status=ONGOING)
 
 ref over "Watcher Decision Engine"
   Trigger audit in the

doc/source/image_src/plantuml/sequence_create_audit_template.txt

@@ -2,7 +2,7 @@
 
 actor Administrator
 
-Administrator -> "Watcher CLI" : watcher audit-template-create <name> <goal> \
+Administrator -> "Watcher CLI" : watcher audittemplate create <name> <goal> \
 [--strategy-uuid <strategy>]
 "Watcher CLI" -> "Watcher API" : POST audit_template(parameters)
 

doc/source/image_src/plantuml/sequence_launch_action_plan.txt

@@ -2,7 +2,7 @@
 
 actor Administrator
 
-Administrator -> "Watcher CLI" : watcher action-plan-start <action_plan_uuid>
+Administrator -> "Watcher CLI" : watcher actionplan start <action_plan_uuid>
 
 "Watcher CLI" -> "Watcher API" : PATCH action_plan(state=PENDING)
 "Watcher API" -> "Watcher Database" : action_plan.state=PENDING