Move terminology definition to class related

As of now, the glossary defined in our documentation reflects the
current state of the codebase. In order to avoid any discrepancy
between the codebase and each definition, the objective here is to
gather both in a single place and link it into the rst documentation
via a custom directive.
Also re-aligned the requirements with liberty for doc.

Change-Id: I3089fd9f948b948115672f10937b1500b96ce180
Partial-Bug: #1526671

watcher/api/controllers/v1/action.py

@@ -15,6 +15,43 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An :ref:`Action <action_definition>` is what enables Watcher to transform the
+current state of a :ref:`Cluster <cluster_definition>` after an
+:ref:`Audit <audit_definition>`.
+
+An :ref:`Action <action_definition>` is an atomic task which changes the
+current state of a target :ref:`Managed resource <managed_resource_definition>`
+of the OpenStack :ref:`Cluster <cluster_definition>` such as:
+
+-  Live migration of an instance from one compute node to another compute
+   node with Nova
+-  Changing the power level of a compute node (ACPI level, ...)
+-  Changing the current state of an hypervisor (enable or disable) with Nova
+
+In most cases, an :ref:`Action <action_definition>` triggers some concrete
+commands on an existing OpenStack module (Nova, Neutron, Cinder, Ironic, etc.)
+via a :ref:`Primitive <primitive_definition>`.
+
+An :ref:`Action <action_definition>` has a life-cycle and its current state may
+be one of the following:
+
+-  **PENDING** : the :ref:`Action <action_definition>` has not been executed
+   yet by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **ONGOING** : the :ref:`Action <action_definition>` is currently being
+   processed by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **SUCCEEDED** : the :ref:`Action <action_definition>` has been executed
+   successfully
+-  **FAILED** : an error occured while trying to execute the
+   :ref:`Action <action_definition>`
+-  **DELETED** : the :ref:`Action <action_definition>` is still stored in the
+   :ref:`Watcher database <watcher_database_definition>` but is not returned
+   any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Action <action_definition>` was in **PENDING** or
+   **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+"""
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/action_plan.py

@@ -15,6 +15,60 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An :ref:`Action Plan <action_plan_definition>` is a flow of
+:ref:`Actions <action_definition>` that should be executed in order to satisfy
+a given :ref:`Goal <goal_definition>`.
+
+An :ref:`Action Plan <action_plan_definition>` is generated by Watcher when an
+:ref:`Audit <audit_definition>` is successful which implies that the
+:ref:`Strategy <strategy_definition>`
+which was used has found a :ref:`Solution <solution_definition>` to achieve the
+:ref:`Goal <goal_definition>` of this :ref:`Audit <audit_definition>`.
+
+In the default implementation of Watcher, an
+:ref:`Action Plan <action_plan_definition>`
+is only composed of successive :ref:`Actions <action_definition>`
+(i.e., a Workflow of :ref:`Actions <action_definition>` belonging to a unique
+branch).
+
+However, Watcher provides abstract interfaces for many of its components,
+allowing other implementations to generate and handle more complex
+:ref:`Action Plan(s) <action_plan_definition>`
+composed of two types of Action Item(s):
+
+-  simple :ref:`Actions <action_definition>`: atomic tasks, which means it
+   can not be split into smaller tasks or commands from an OpenStack point of
+   view.
+-  composite Actions: which are composed of several simple
+   :ref:`Actions <action_definition>`
+   ordered in sequential and/or parallel flows.
+
+An :ref:`Action Plan <action_plan_definition>` may be described using
+standard workflow model description formats such as
+`Business Process Model and Notation 2.0 (BPMN 2.0) <http://www.omg.org/spec/BPMN/2.0/>`_
+or `Unified Modeling Language (UML) <http://www.uml.org/>`_.
+
+An :ref:`Action Plan <action_plan_definition>` has a life-cycle and its current
+state may be one of the following:
+
+-  **RECOMMENDED** : the :ref:`Action Plan <action_plan_definition>` is waiting
+   for a validation from the :ref:`Administrator <administrator_definition>`
+-  **ONGOING** : the :ref:`Action Plan <action_plan_definition>` is currently
+   being processed by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **SUCCEEDED** : the :ref:`Action Plan <action_plan_definition>` has been
+   executed successfully (i.e. all :ref:`Actions <action_definition>` that it
+   contains have been executed successfully)
+-  **FAILED** : an error occured while executing the
+   :ref:`Action Plan <action_plan_definition>`
+-  **DELETED** : the :ref:`Action Plan <action_plan_definition>` is still
+   stored in the :ref:`Watcher database <watcher_database_definition>` but is
+   not returned any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Action Plan <action_plan_definition>` was in
+   **PENDING** or **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+"""  # noqa
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/audit.py

@@ -15,6 +15,40 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+In the Watcher system, an :ref:`Audit <audit_definition>` is a request for
+optimizing a :ref:`Cluster <cluster_definition>`.
+
+The optimization is done in order to satisfy one :ref:`Goal <goal_definition>`
+on a given :ref:`Cluster <cluster_definition>`.
+
+For each :ref:`Audit <audit_definition>`, the Watcher system generates an
+:ref:`Action Plan <action_plan_definition>`.
+
+An :ref:`Audit <audit_definition>` has a life-cycle and its current state may
+be one of the following:
+
+-  **PENDING** : a request for an :ref:`Audit <audit_definition>` has been
+   submitted (either manually by the
+   :ref:`Administrator <administrator_definition>` or automatically via some
+   event handling mechanism) and is in the queue for being processed by the
+   :ref:`Watcher Decision Engine <watcher_decision_engine_definition>`
+-  **ONGOING** : the :ref:`Audit <audit_definition>` is currently being
+   processed by the
+   :ref:`Watcher Decision Engine <watcher_decision_engine_definition>`
+-  **SUCCEEDED** : the :ref:`Audit <audit_definition>` has been executed
+   successfully (note that it may not necessarily produce a
+   :ref:`Solution <solution_definition>`).
+-  **FAILED** : an error occured while executing the
+   :ref:`Audit <audit_definition>`
+-  **DELETED** : the :ref:`Audit <audit_definition>` is still stored in the
+   :ref:`Watcher database <watcher_database_definition>` but is not returned
+   any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Audit <audit_definition>` was in **PENDING** or
+   **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+"""
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/audit_template.py

@@ -15,6 +15,39 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An :ref:`Audit <audit_definition>` may be launched several times with the same
+settings (:ref:`Goal <goal_definition>`, thresholds, ...). Therefore it makes
+sense to save those settings in some sort of Audit preset object, which is
+known as an :ref:`Audit Template <audit_template_definition>`.
+
+An :ref:`Audit Template <audit_template_definition>` contains at least the
+:ref:`Goal <goal_definition>` of the :ref:`Audit <audit_definition>`.
+
+It may also contain some error handling settings indicating whether:
+
+-  :ref:`Watcher Applier <watcher_applier_definition>` stops the
+   entire operation
+-  :ref:`Watcher Applier <watcher_applier_definition>` performs a rollback
+
+and how many retries should be attempted before failure occurs (also the latter
+can be complex: for example the scenario in which there are many first-time
+failures on ultimately successful :ref:`Actions <action_definition>`).
+
+Moreover, an :ref:`Audit Template <audit_template_definition>` may contain some
+settings related to the level of automation for the
+:ref:`Action Plan <action_plan_definition>` that will be generated by the
+:ref:`Audit <audit_definition>`.
+A flag will indicate whether the :ref:`Action Plan <action_plan_definition>`
+will be launched automatically or will need a manual confirmation from the
+:ref:`Administrator <administrator_definition>`.
+
+Last but not least, an :ref:`Audit Template <audit_template_definition>` may
+contain a list of extra parameters related to the
+:ref:`Strategy <strategy_definition>` configuration. These parameters can be
+provided as a list of key-value pairs.
+"""
+
 import datetime
 
 import pecan

watcher/api/controllers/v1/goal.py

@@ -15,6 +15,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+A :ref:`Goal <goal_definition>` is a human readable, observable and measurable
+end result having one objective to be achieved.
+
+Here are some examples of :ref:`Goals <goal_definition>`:
+
+-  minimize the energy consumption
+-  minimize the number of compute nodes (consolidation)
+-  balance the workload among compute nodes
+-  minimize the license cost (some softwares have a licensing model which is
+   based on the number of sockets or cores where the software is deployed)
+-  find the most appropriate moment for a planned maintenance on a
+   given group of host (which may be an entire availability zone):
+   power supply replacement, cooling system replacement, hardware
+   modification, ...
+"""
+
 from oslo_config import cfg
 
 import pecan