Documentation for plugins-parameters

In this changeset, I updated the documentation to explain how to
add configuration options for each type of plugin.

Partially Implements: plugins-parameters

Change-Id: Ifd373da64207110492b4a62f1cb7f13b029a45d2

doc/source/dev/plugin/action-plugin.rst

@@ -55,7 +55,7 @@ Here is an example showing how you can write a plugin called ``DummyAction``:
     from watcher.applier.actions import base
 
 
-    class DummyAction(baseBaseAction):
+    class DummyAction(base.BaseAction):
 
         @property
         def schema(self):
@@ -90,11 +90,53 @@ Input validation
 
 As you can see in the previous example, we are using `Voluptuous`_ to validate
 the input parameters of an action. So if you want to learn more about how to
-work with `Voluptuous`_, you can have a look at their `documentation`_ here:
+work with `Voluptuous`_, you can have a look at their `documentation`_:
 
 .. _Voluptuous: https://github.com/alecthomas/voluptuous
 .. _documentation: https://github.com/alecthomas/voluptuous/blob/master/README.md
 
+
+Define configuration parameters
+===============================
+
+At this point, you have a fully functional action. However, in more complex
+implementation, you may want to define some configuration options so one can
+tune the action to its needs. To do so, you can implement the
+:py:meth:`~.Loadable.get_config_opts` class method as followed:
+
+.. code-block:: python
+
+    from oslo_config import cfg
+
+    class DummyAction(base.BaseAction):
+
+        # [...]
+
+        def execute(self):
+            assert self.config.test_opt == 0
+
+        def get_config_opts(self):
+            return [
+                cfg.StrOpt('test_opt', help="Demo Option.", default=0),
+                # Some more options ...
+            ]
+
+The configuration options defined within this class method will be included
+within the global ``watcher.conf`` configuration file under a section named by
+convention: ``{namespace}.{plugin_name}``. In our case, the ``watcher.conf``
+configuration would have to be modified as followed:
+
+.. code-block:: ini
+
+    [watcher_actions.dummy]
+    # Option used for testing.
+    test_opt = test_value
+
+Then, the configuration options you define within this method will then be
+injected in each instantiated object via the  ``config`` parameter of the
+:py:meth:`~.BaseAction.__init__` method.
+
+
 Abstract Plugin Class
 =====================
 
@@ -103,6 +145,7 @@ should implement:
 
 .. autoclass:: watcher.applier.actions.base.BaseAction
     :members:
+    :special-members: __init__
     :noindex:
 
     .. py:attribute:: schema

doc/source/dev/plugin/planner-plugin.rst

@@ -69,6 +69,49 @@ examples, have a look at the implementation of planners already provided by
 Watcher like :py:class:`~.DefaultPlanner`. A list with all available planner
 plugins can be found :ref:`here <watcher_planners>`.
 
+
+Define configuration parameters
+===============================
+
+At this point, you have a fully functional planner. However, in more complex
+implementation, you may want to define some configuration options so one can
+tune the planner to its needs. To do so, you can implement the
+:py:meth:`~.Loadable.get_config_opts` class method as followed:
+
+.. code-block:: python
+
+    from oslo_config import cfg
+
+    class DummyPlanner(base.BasePlanner):
+
+        # [...]
+
+        def schedule(self, context, audit_uuid, solution):
+            assert self.config.test_opt == 0
+            # [...]
+
+        def get_config_opts(self):
+            return [
+                cfg.StrOpt('test_opt', help="Demo Option.", default=0),
+                # Some more options ...
+            ]
+
+The configuration options defined within this class method will be included
+within the global ``watcher.conf`` configuration file under a section named by
+convention: ``{namespace}.{plugin_name}``. In our case, the ``watcher.conf``
+configuration would have to be modified as followed:
+
+.. code-block:: ini
+
+    [watcher_planners.dummy]
+    # Option used for testing.
+    test_opt = test_value
+
+Then, the configuration options you define within this method will then be
+injected in each instantiated object via the  ``config`` parameter of the
+:py:meth:`~.BasePlanner.__init__` method.
+
+
 Abstract Plugin Class
 =====================
 
@@ -77,6 +120,7 @@ should implement:
 
 .. autoclass:: watcher.decision_engine.planner.base.BasePlanner
     :members:
+    :special-members: __init__
     :noindex:
 
 

doc/source/dev/plugin/strategy-plugin.rst

@@ -163,8 +163,8 @@ modify your ``NewStrategy`` plugin so it now achieves the latter:
 
     class NewStrategy(NewGoalBaseStrategy):
 
-        def __init__(self, osc=None):
-            super(NewStrategy, self).__init__(osc)
+        def __init__(self, config, osc=None):
+            super(NewStrategy, self).__init__(config, osc)
 
         def execute(self, original_model):
             self.solution.add_action(action_type="nop",
@@ -185,6 +185,49 @@ modify your ``NewStrategy`` plugin so it now achieves the latter:
             return "New strategy"
 
 
+Define configuration parameters
+===============================
+
+At this point, you have a fully functional strategy. However, in more complex
+implementation, you may want to define some configuration options so one can
+tune the strategy to its needs. To do so, you can implement the
+:py:meth:`~.Loadable.get_config_opts` class method as followed:
+
+.. code-block:: python
+
+    from oslo_config import cfg
+
+    class NewStrategy(NewGoalBaseStrategy):
+
+        # [...]
+
+        def execute(self, original_model):
+            assert self.config.test_opt == 0
+            # [...]
+
+        def get_config_opts(self):
+            return [
+                cfg.StrOpt('test_opt', help="Demo Option.", default=0),
+                # Some more options ...
+            ]
+
+
+The configuration options defined within this class method will be included
+within the global ``watcher.conf`` configuration file under a section named by
+convention: ``{namespace}.{plugin_name}``. In our case, the ``watcher.conf``
+configuration would have to be modified as followed:
+
+.. code-block:: ini
+
+    [watcher_strategies.new_strategy]
+    # Option used for testing.
+    test_opt = test_value
+
+Then, the configuration options you define within this method will then be
+injected in each instantiated object via the  ``config`` parameter of the
+:py:meth:`~.BaseStrategy.__init__` method.
+
+
 Abstract Plugin Class
 =====================
 
@@ -192,6 +235,7 @@ Here below is the abstract :py:class:`~.BaseStrategy` class:
 
 .. autoclass:: watcher.decision_engine.strategy.strategies.base.BaseStrategy
     :members:
+    :special-members: __init__
     :noindex:
 
 .. _strategy_plugin_add_entrypoint:

doc/source/dev/plugins.rst

@@ -9,6 +9,10 @@
 Available Plugins
 =================
 
+In this section we present all the plugins that are shipped along with Watcher.
+If you want to know which plugins your Watcher services have access to, you can
+use the :ref:`Guru Meditation Reports <watcher_gmr>` to display them.
+
 .. _watcher_strategies:
 
 Strategies