Adjust images in the docs and other small fixes

* Some ".. image:" RST directives changed to ".. figure:" where
  it's more suitable.
* All images moved to subfolder where they're used
* Fixed indentation in the Workflow Language specification
* Other minor changes in docs

Change-Id: If2f206a5191d1eecdcf95e1f7b44a87968432876

doc/source/user/asynchronous_actions.rst

@@ -6,7 +6,7 @@ How to work with asynchronous actions
 Concept
 *******
 
-.. image:: /img/Mistral_actions.png
+.. image:: /user/terminology/img/actions.png
 
 During a workflow execution Mistral eventually runs actions. Action
 is a particular function (or a piece of work) that a workflow task

doc/source/user/cookbooks/cloud_cron.rst

@@ -64,8 +64,10 @@ script running on a single machine that is responsible for solving this
 task just fails for whatever reason then the whole process of updating
 a hundred servers will not complete and end up in an unknown state.
 
-.. image:: img/cloud_cron_updating_multiple_servers.png
-    :alt: Updating multiple tenant servers
+.. figure:: img/cloud_cron_updating_multiple_servers.png
+    :align: center
+
+    Figure 1. Updating multiple tenant servers
 
 So that shows that we need to take care of at least:
 
@@ -192,8 +194,10 @@ we can actually ssh other VMs. That's why we're using special action called
 "std.ssh_proxied" where "proxied" means that we have a proxy VM to access
 all tenant VMs.
 
-.. image:: img/ssh_proxied.png
-    :alt: Ssh access through a gateway VM
+.. figure:: img/ssh_proxied.png
+    :align: center
+
+    Figure 2. Ssh access through a gateway VM.
 
 Mistral is a distributed highly-available system and it’s designed not only
 to survive infrastructural failures but also keep its workflows running.

doc/source/user/terminology/actions.rst

@@ -17,7 +17,7 @@ result of the action. The third-party service should send a request to the
 Mistral API and provide information corresponding to the *action execution* and
 its state and result.
 
-.. image:: /img/Mistral_actions.png
+.. image:: img/actions.png
 
 :doc:`How to work with asynchronous actions </user/asynchronous_actions>`
 
@@ -27,7 +27,7 @@ System actions
 System actions are provided by Mistral out of the box and are available to all
 users. Additional actions can be added via the custom action plugin mechanism.
 
-:doc:`How to write an Action Plugin
+:doc:`How to create a custom action
 </developer/extensions/creating_custom_action>`
 
 

doc/source/user/terminology/cron_triggers.rst

@@ -5,8 +5,9 @@ Cron trigger is an object allowing to run workflow on a schedule. User
 specifies what workflow with what input needs to be run and also specifies
 how often it should be run.
 
-.. image:: /img/Mistral_cron_trigger.png
+.. image:: img/cron_trigger.png
     :align: center
 
 Cron-pattern is used to describe the frequency of execution in Mistral.
-To see more about cron-patterns, refer to `Cron expression <https://en.wikipedia.org/wiki/Cron#CRON_expression>`_
+To see more about cron-patterns, refer to
+`Cron expression <https://en.wikipedia.org/wiki/Cron#CRON_expression>`_

doc/source/user/terminology/workbooks.rst

@@ -18,7 +18,7 @@ name as a prefix for generating final names of workflows and actions included
 into the workbook. To illustrate this principle let's take a look at the
 figure below:
 
-.. image:: /img/Mistral_workbook_namespacing.png
+.. image:: img/workbook_namespacing.png
     :align: center
 
 So after a workbook has been uploaded its workflows and actions become

doc/source/user/terminology/workflows.rst

@@ -56,7 +56,7 @@ workflow has a notion of transition. Direct workflow is considered to be
 completed if there aren't any transitions left that could be used to
 jump to next tasks.
 
-.. image:: /img/Mistral_direct_workflow.png
+.. image:: img/direct_workflow.png
 
 YAML example of direct workflow
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -97,7 +97,7 @@ task that needs to be completed, it can be conventionally called 'target
 task'. When Mistral Engine starts a workflow it recursively identifies
 all the dependencies that need to be completed first.
 
-.. image:: /img/Mistral_reverse_workflow.png
+.. image:: img/reverse_workflow.png
 
 The figure explains how reverse workflow works. In the example, task
 **T1** is chosen a target task. So when the workflow starts Mistral will

doc/source/user/use_cases/long_running_business_process.rst

@@ -43,10 +43,11 @@ Mistral is a perfect fit for being this kind of coordinator. In order to
 illustrate everything described so far, let’s consider an imaginary workflow
 of calculating employees’ salaries in an enterprise.
 
-.. image:: img/long_running_business_process.png
-    :alt: Picture 1. Mistral maintains business workflows spanning multiple systems.
+.. figure:: img/long_running_business_process.png
     :align: center
 
+    Figure 1. Mistral maintains business workflows spanning multiple systems.
+
 Given an employee full name (or id) such workflow may include the following
 computation steps:
 

doc/source/user/wf_lang_v2.rst

@@ -532,7 +532,7 @@ starts after another one depending on produced result. So direct workflow has a
 notion of transition. Direct workflow is considered to be completed if there
 aren't any transitions left that could be used to jump to next tasks.
 
-.. image:: /img/Mistral_direct_workflow.png
+.. image:: /user/terminology/img/direct_workflow.png
 
 Figure 1. Mistral Direct Workflow.
 
@@ -962,7 +962,7 @@ be completed, it can be conventionally called 'target task'. When Mistral
 Engine starts a workflow it recursively identifies all the dependencies that
 need to be completed first.
 
-.. image:: /img/Mistral_reverse_workflow.png
+.. image:: /user/terminology/img/reverse_workflow.png
 
 Figure 2 explains how reverse workflow works. In the example, task **T1** is
 chosen a target task. So when the workflow starts Mistral will run only tasks
@@ -1421,7 +1421,7 @@ name as a prefix for generating final names of workflows, actions and triggers
 included into the workbook. To illustrate this principle let's take a look at
 the figure below.
 
-.. image:: /img/Mistral_workbook_namespacing.png
+.. image:: /user/terminology/img/workbook_namespacing.png
 
 So after a workbook has been uploaded its workflows and actions become
 independent objects but with slightly different names.
@@ -1526,36 +1526,36 @@ Signature:
 
 Description:
 
-  This function allows users to filter all tasks by workflow execution id
-  and/or state. In addition, it is possible to get task executions recursively
-  and flatten the task executions list.
+This function allows users to filter all tasks by workflow execution id
+and/or state. In addition, it is possible to get task executions recursively
+and flatten the task executions list.
 
 Parameters:
 
-  #. **workflow_execution_id** - If provided the tasks function will return
-     task executions for a specific workflow execution (either the current
-     execution or a different one). Otherwise it will return all task
-     executions that match the other parameters. *Optional.*
-  #. **recursive** - This parameter is a boolean value, if it is true then all
-     task executions within nested workflow executions will be returned. This
-     is usually used in combination with a specific workflow_execution_id
-     where you still want to see nested workflow's task executions. *Optional.*
-     False by default.
-  #. **state** - If provided, the task executions will be filtered by their
-     current state. If state isn't provided, all task executions that match the
-     other parameters will be returned . *Optional.*
-  #. **flat** - if true, only list the task executions that match at least one
-     of the next conditions:
+#. **workflow_execution_id** - If provided the tasks function will return
+   task executions for a specific workflow execution (either the current
+   execution or a different one). Otherwise it will return all task
+   executions that match the other parameters. *Optional.*
+#. **recursive** - This parameter is a boolean value, if it is true then all
+   task executions within nested workflow executions will be returned. This
+   is usually used in combination with a specific workflow_execution_id
+   where you still want to see nested workflow's task executions. *Optional.*
+   False by default.
+#. **state** - If provided, the task executions will be filtered by their
+   current state. If state isn't provided, all task executions that match the
+   other parameters will be returned . *Optional.*
+#. **flat** - if true, only list the task executions that match at least one
+   of the next conditions:
 
-       * task executions of type action
-       * task executions of type workflow that have a different state from the
-         workflow execution they triggered. For example, if used with a
-         specific workflow_execution_id and the state ERROR it will return
-         tasks that erred despite the workflow succeeding. This can mean that
-         there was an error in the task itself, like an invalid expression in
-         publish.
+   * task executions of type action
+   * task executions of type workflow that have a different state from the
+     workflow execution they triggered. For example, if used with a
+     specific workflow_execution_id and the state ERROR it will return
+     tasks that erred despite the workflow succeeding. This can mean that
+     there was an error in the task itself, like an invalid expression in
+     publish.
 
-     *Optional.* False by default.
+   *Optional.* False by default.
 
 Example:
 
@@ -1585,10 +1585,6 @@ Workflow definition:
 
 Task publish result (partial to keep the documentation short):
 
-.. warning::
-  The return value for each task execution hasn't been finalized and isn't
-  considered stable. It may change in a future Mistral release.
-
 .. code-block:: json
 
   {
@@ -1679,34 +1675,34 @@ Signature:
 
 Description:
 
-  This function allows users to filter all executions by execution id,
-  root_execution_id ,state and/or created_at time.
+This function allows users to filter all executions by execution id,
+root_execution_id ,state and/or created_at time.
 
 Parameters:
 
-  #. **id** - If provided will return a list of executions with that id.
-     Otherwise it will return all executions that match the other
-     parameters. *Optional.*
-  #. **root_execution_id** - Similar to id above, if provided will return
-     a list of executions with that root_execution_id. Otherwise it will
-     return all executions that match the other parameters. *Optional.*
-     False by default.
-  #. **state** - If provided, the executions will be filtered by their
-     current state. If state isn't provided, all executions that match the
-     other parameters will be returned . *Optional.*
-  #. **from_time** - If provided, the executions will be filtered by their
-     created_at time being greater or equal to the from_time parameter.
-     If from_time isn't provided, all executions that match the
-     other parameters will be returned. from_time parameter can be provided
-     in the format *YYYY-MM-DD hh:mm:ss*
-     *Optional.*
-  #. **to_time** - If provided, the executions will be filtered by their
-     created_at time being less than to the from_time parameter (less than but
-     not less than equal as the from_time parameter does)
-     If to_time isn't provided, all executions that match the
-     other parameters will be returned. to_time parameter can be provided
-     in the format *YYYY-MM-DD hh:mm:ss*
-     *Optional.*
+#. **id** - If provided will return a list of executions with that id.
+   Otherwise it will return all executions that match the other
+   parameters. *Optional.*
+#. **root_execution_id** - Similar to id above, if provided will return
+   a list of executions with that root_execution_id. Otherwise it will
+   return all executions that match the other parameters. *Optional.*
+   False by default.
+#. **state** - If provided, the executions will be filtered by their
+   current state. If state isn't provided, all executions that match the
+   other parameters will be returned . *Optional.*
+#. **from_time** - If provided, the executions will be filtered by their
+   created_at time being greater or equal to the from_time parameter.
+   If from_time isn't provided, all executions that match the
+   other parameters will be returned. from_time parameter can be provided
+   in the format *YYYY-MM-DD hh:mm:ss*
+   *Optional.*
+#. **to_time** - If provided, the executions will be filtered by their
+   created_at time being less than to the from_time parameter (less than but
+   not less than equal as the from_time parameter does)
+   If to_time isn't provided, all executions that match the
+   other parameters will be returned. to_time parameter can be provided
+   in the format *YYYY-MM-DD hh:mm:ss*
+   *Optional.*
 
 Example: