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/decision_engine/solution/base.py

@@ -16,6 +16,39 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+"""
+A :ref:`Solution <solution_definition>` is a set of
+:ref:`Actions <action_definition>` generated by a
+:ref:`Strategy <strategy_definition>` (i.e., an algorithm) in order to achieve
+the :ref:`Goal <goal_definition>` of an :ref:`Audit <audit_definition>`.
+
+A :ref:`Solution <solution_definition>` is different from an
+:ref:`Action Plan <action_plan_definition>` because it contains the
+non-scheduled list of :ref:`Actions <action_definition>` which is produced by a
+:ref:`Strategy <strategy_definition>`. In other words, the list of Actions in
+a :ref:`Solution <solution_definition>` has not yet been re-ordered by the
+:ref:`Watcher Planner <watcher_planner_definition>`.
+
+Note that some algorithms (i.e. :ref:`Strategies <strategy_definition>`) may
+generate several :ref:`Solutions <solution_definition>`. This gives rise to the
+problem of determining which :ref:`Solution <solution_definition>` should be
+applied.
+
+Two approaches to dealing with this can be envisaged:
+
+-  **fully automated mode**: only the :ref:`Solution <solution_definition>`
+ with the highest ranking (i.e., the highest
+   :ref:`Optimization Efficiency <efficiency_definition>`)
+   will be sent to the :ref:`Watcher Planner <watcher_planner_definition>` and
+   translated into concrete :ref:`Actions <action_definition>`.
+-  **manual mode**: several :ref:`Solutions <solution_definition>` are proposed
+   to the :ref:`Administrator <administrator_definition>` with a detailed
+   measurement of the estimated
+   :ref:`Optimization Efficiency <efficiency_definition>` and he/she decides
+   which one will be launched.
+"""
+
 import abc
 import six