RST directive to discover and generate drivers doc

This patchset introduces a new custom directive called 'drivers-doc'
which loads all available drivers under a given namespace and import
their respective docstring into the .rst document.

This patchset also contains some modification/addition to the
docstring of these drivers to make the final document complete.

Change-Id: Ib3df59fa45cea9d11d20fb73a5f0f1d564135bca
Closes-Bug: #1536218
Closes-Bug: #1536735

watcher/decision_engine/planner/default.py

@@ -28,6 +28,13 @@ LOG = log.getLogger(__name__)
 
 
 class DefaultPlanner(base.BasePlanner):
+    """Default planner implementation
+
+    This implementation comes with basic rules with a fixed set of action types
+    that are weighted. An action having a lower weight will be scheduled before
+    the other ones.
+    """
+
     priorities = {
         'nop': 0,
         'sleep': 1,

watcher/decision_engine/strategy/strategies/basic_consolidation.py

@@ -16,6 +16,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+"""
+*Good server consolidation strategy*
+
+Consolidation of VMs is essential to achieve energy optimization in cloud
+environments such as OpenStack. As VMs are spinned up and/or moved over time,
+it becomes necessary to migrate VMs among servers to lower the costs. However,
+migration of VMs introduces runtime overheads and consumes extra energy, thus
+a good server consolidation strategy should carefully plan for migration in
+order to both minimize energy consumption and comply to the various SLAs.
+"""
 
 from oslo_log import log
 
@@ -32,6 +42,29 @@ LOG = log.getLogger(__name__)
 
 
 class BasicConsolidation(base.BaseStrategy):
+    """Basic offline consolidation using live migration
+
+    *Description*
+
+    This is server consolidation algorithm which not only minimizes the overall
+    number of used servers, but also minimizes the number of migrations.
+
+    *Requirements*
+
+    * You must have at least 2 physical compute nodes to run this strategy.
+
+    *Limitations*
+
+    - It has been developed only for tests.
+    - It assumes that the virtual machine and the compute node are on the same
+      private network.
+    - It assume that live migrations are possible
+
+    *Spec URL*
+
+    <None>
+    """
+
     DEFAULT_NAME = "basic"
     DEFAULT_DESCRIPTION = "Basic offline consolidation"
 
@@ -45,31 +78,11 @@ class BasicConsolidation(base.BaseStrategy):
                  osc=None):
         """Basic offline Consolidation using live migration
 
-    The basic consolidation algorithm has several limitations.
-    It has been developed only for tests.
-    eg: The BasicConsolidation assumes that the virtual mahine and
-    the compute node are on the same private network.
-
-    Good Strategy :
-    The workloads of the VMs are changing over the time
-    and often tend to migrate from one physical machine to another.
-    Hence, the traditional and offline heuristics such as bin packing
-    are not applicable for the placement VM in cloud computing.
-    So, the decision Engine optimizer provides placement strategy considering
-    not only the performance effects but also the workload characteristics of
-    VMs and others metrics like the power consumption and
-    the tenants constraints (SLAs).
-
-    The watcher optimizer uses an online VM placement technique
-    based on machine learning and meta-heuristics that must handle :
-    - multi-objectives
-    - Contradictory objectives
-    - Adapt to changes dynamically
-    - Fast convergence
-
-        :param name: the name of the strategy
-        :param description: a description of the strategy
-        :param osc: an OpenStackClients object
+        :param name: The name of the strategy (Default: "basic")
+        :param description: The description of the strategy
+                            (Default: "Basic offline consolidation")
+        :param osc: An :py:class:`~watcher.common.clients.OpenStackClients`
+                    instance
         """
         super(BasicConsolidation, self).__init__(name, description, osc)
 

watcher/decision_engine/strategy/strategies/dummy_strategy.py

@@ -24,6 +24,26 @@ LOG = log.getLogger(__name__)
 
 
 class DummyStrategy(base.BaseStrategy):
+    """Dummy strategy used for integration testing via Tempest
+
+    *Description*
+
+    This strategy does not provide any useful optimization. Indeed, its only
+    purpose is to be used by Tempest tests.
+
+    *Requirements*
+
+    <None>
+
+    *Limitations*
+
+    Do not use in production.
+
+    *Spec URL*
+
+    <None>
+    """
+
     DEFAULT_NAME = "dummy"
     DEFAULT_DESCRIPTION = "Dummy Strategy"
 

watcher/decision_engine/strategy/strategies/outlet_temp_control.py

@@ -16,6 +16,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+"""
+*Good Thermal Strategy*:
+
+Towards to software defined infrastructure, the power and thermal
+intelligences is being adopted to optimize workload, which can help
+improve efficiency, reduce power, as well as to improve datacenter PUE
+and lower down operation cost in data center.
+Outlet (Exhaust Air) Temperature is one of the important thermal
+telemetries to measure thermal/workload status of server.
+"""
+
 from oslo_log import log
 
 from watcher._i18n import _LE
@@ -30,6 +42,34 @@ LOG = log.getLogger(__name__)
 
 
 class OutletTempControl(base.BaseStrategy):
+    """[PoC] Outlet temperature control using live migration
+
+    *Description*
+
+    It is a migration strategy based on the outlet temperature of compute
+    hosts. It generates solutions to move a workload whenever a server's
+    outlet temperature is higher than the specified threshold.
+
+    *Requirements*
+
+    * Hardware: All computer hosts should support IPMI and PTAS technology
+    * Software: Ceilometer component ceilometer-agent-ipmi running
+      in each compute host, and Ceilometer API can report such telemetry
+      ``hardware.ipmi.node.outlet_temperature`` successfully.
+    * You must have at least 2 physical compute hosts to run this strategy.
+
+    *Limitations*
+
+    - This is a proof of concept that is not meant to be used in production
+    - We cannot forecast how many servers should be migrated. This is the
+      reason why we only plan a single virtual machine migration at a time.
+      So it's better to use this algorithm with `CONTINUOUS` audits.
+    - It assume that live migrations are possible
+
+    *Spec URL*
+
+    https://github.com/openstack/watcher-specs/blob/master/specs/mitaka/approved/outlet-temperature-based-strategy.rst
+    """  # noqa
 
     DEFAULT_NAME = "outlet_temp_control"
     DEFAULT_DESCRIPTION = "outlet temperature based migration strategy"
@@ -42,29 +82,7 @@ class OutletTempControl(base.BaseStrategy):
 
     def __init__(self, name=DEFAULT_NAME, description=DEFAULT_DESCRIPTION,
                  osc=None):
-        """[PoC]Outlet temperature control using live migration
-
-        It is a migration strategy based on the Outlet Temperature of physical
-        servers. It generates solutions to move a workload whenever a server’s
-        outlet temperature is higher than the specified threshold. As of now,
-        we cannot forecast how many instances should be migrated. This is the
-        reason why we simply plan a single virtual machine migration.
-        So it's better to use this algorithm with CONTINUOUS audits.
-
-        Requirements:
-        * Hardware: computer node should support IPMI and PTAS technology
-        * Software: Ceilometer component ceilometer-agent-ipmi running
-          in each compute node, and Ceilometer API can report such telemetry
-          "hardware.ipmi.node.outlet_temperature" successfully.
-        * You must have at least 2 physical compute nodes to run this strategy.
-
-        Good Strategy:
-        Towards to software defined infrastructure, the power and thermal
-        intelligences is being adopted to optimize workload, which can help
-        improve efficiency, reduce power, as well as to improve datacenter PUE
-        and lower down operation cost in data center.
-        Outlet(Exhaust Air) Temperature is one of the important thermal
-        telemetries to measure thermal/workload status of server.
+        """Outlet temperature control using live migration
 
         :param name: the name of the strategy
         :param description: a description of the strategy