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

@@ -17,6 +17,14 @@
 # limitations under the License.
 #
 
+"""
+This component is in charge of executing the
+:ref:`Action Plan <action_plan_definition>` built by the
+:ref:`Watcher Decision Engine <watcher_decision_engine_definition>`.
+
+See :doc:`architecture` for more details on this component.
+"""
+
 import abc
 import six
 

watcher/applier/primitives/base.py

@@ -16,6 +16,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+"""
+A :ref:`Primitive <primitive_definition>` is the component that carries out a
+certain type of atomic :ref:`Actions <action_definition>` on a given
+:ref:`Managed resource <managed_resource_definition>` (nova, swift, neutron,
+glance,..). A :ref:`Primitive <primitive_definition>` is a part of the
+:ref:`Watcher Applier <watcher_applier_definition>` module.
+
+For example, there can be a :ref:`Primitive <primitive_definition>` which is
+responsible for creating a snapshot of a given instance on a Nova compute node.
+This :ref:`Primitive <primitive_definition>` knows exactly how to send
+the appropriate commands to Nova for this type of
+:ref:`Actions <action_definition>`.
+"""
+
 import abc
 import six
 from watcher.applier.promise import Promise