Remove all sphinx warnings

This patch set fixes all sphinx warnings and makes
https://docs.openstack.org/watcher/latest/configuration/index.html
available.

Change-Id: I76a715c10cb1d582419ff37869093fa9b8678310

.gitignore

@@ -44,7 +44,7 @@ output/*/index.html
 doc/build
 doc/source/api/*
 doc/source/samples
-doc/source/watcher.conf.sample
+doc/source/_static/*.sample
 !doc/source/api/index.rst
 !doc/source/api/v1.rst
 

doc/source/admin/conf-files.rst

@@ -1,14 +0,0 @@
-.. _watcher_sample_configuration_files:
-
-==================================
-Watcher sample configuration files
-==================================
-
-watcher.conf
-~~~~~~~~~~~~
-
-The ``watcher.conf`` file contains most of the options to configure the
-Watcher services.
-
-.. literalinclude:: ../watcher.conf.sample
-   :language: ini

doc/source/admin/index.rst

@@ -6,8 +6,6 @@ Administrator Guide
    :maxdepth: 2
 
    apache-mod-wsgi
-   conf-files
-   configuration
    gmr
    policy
    ways-to-install

doc/source/admin/ways-to-install.rst

@@ -10,7 +10,7 @@ Ways to install Watcher
 
 This document describes some ways to install Watcher in order to use it.
 If you are intending to develop on or with Watcher,
-please read :doc:`../dev/environment`.
+please read :doc:`../contributor/environment`.
 
 Prerequisites
 -------------
@@ -78,9 +78,10 @@ Install the Watcher modules dependencies:
 
     # pip install -r requirements.txt
 
-From here, refer to :doc:`configuration` to declare Watcher as a new service
-into Keystone and to configure its different modules. Once configured, you
-should be able to run the Watcher services by issuing these commands:
+From here, refer to :doc:`../configuration/configuring` to declare Watcher
+as a new service into Keystone and to configure its different modules.
+Once configured, you should be able to run the Watcher services by issuing
+these commands:
 
 .. code-block:: bash
 
@@ -108,7 +109,7 @@ installed on your system.
 
 Once installed, you still need to declare Watcher as a new service into
 Keystone and to configure its different modules, which you can find described
-in :doc:`configuration`.
+in :doc:`../configuration/configuring`.
 
 
 Installing from packages: Debian (experimental)

doc/source/conf.py

@@ -31,8 +31,7 @@ sys.path.insert(0, os.path.abspath('./'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'oslo_config.sphinxconfiggen',
-    'openstackdocstheme',
+    'oslo_config.sphinxext',
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
     'sphinxcontrib.httpdomain',
@@ -41,10 +40,14 @@ extensions = [
     'wsmeext.sphinxext',
     'ext.term',
     'ext.versioned_notifications',
+    'oslo_config.sphinxconfiggen',
+    'openstackdocstheme',
 ]
 
 wsme_protocols = ['restjson']
-config_generator_config_file = '../../etc/watcher/watcher-config-generator.conf'
+config_generator_config_file = [(
+    '../../etc/watcher/oslo-config-generator/watcher.conf',
+    '_static/watcher')]
 sample_config_basename = 'watcher'
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -92,6 +95,8 @@ add_function_parentheses = True
 # unit titles (such as .. function::).
 add_module_names = True
 
+suppress_warnings = ['app.add_directive']
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 

doc/source/config-generator.conf

@@ -1 +0,0 @@
-../../etc/watcher/watcher-config-generator.conf

doc/source/configuration/index.rst

@@ -0,0 +1,5 @@
+.. toctree::
+   :maxdepth: 1
+
+   configuring
+   watcher

doc/source/configuration/watcher.rst

@@ -0,0 +1,11 @@
+.. _watcher_sample_configuration_files:
+
+------------
+watcher.conf
+------------
+
+The ``watcher.conf`` file contains most of the options to configure the
+Watcher services.
+
+.. show-options::
+   :config-file: etc/watcher/oslo-config-generator/watcher.conf

doc/source/contributor/environment.rst

@@ -194,7 +194,7 @@ still need to configure the following sections:
   message bus
 
 So if you need some more details on how to configure one or more of these
-sections, please do have a look at :doc:`../deploy/configuration` before
+sections, please do have a look at :doc:`../configuration/configuring` before
 continuing.
 
 
@@ -240,7 +240,7 @@ To run the Watcher Applier service, use:
     (watcher) $ watcher-applier
 
 Default configuration of these services are available into ``/etc/watcher``
-directory. See :doc:`../deploy/configuration` for details on how Watcher is
+directory. See :doc:`../configuration/configuring` for details on how Watcher is
 configured. By default, Watcher is configured with SQL backends.
 
 

doc/source/contributor/index.rst

@@ -1,8 +1,8 @@
 .. toctree::
    :maxdepth: 1
 
-  environment
-  devstack
-  notifications
-  testing
-  rally_link
+   environment
+   devstack
+   notifications
+   testing
+   rally_link

doc/source/contributor/plugin/goal-plugin.rst

@@ -123,8 +123,9 @@ Here below is how you would proceed to register ``NewGoal`` using pbr_:
         new_goal = thirdparty.new:NewGoal
 
 
-To get a better understanding on how to implement a more advanced goal,
-have a look at the :py:class:`~.ServerConsolidation` class.
+To get a better understanding on how to implement a more advanced goal, have
+a look at the
+:py:class:`watcher.decision_engine.goal.goals.ServerConsolidation` class.
 
 .. _pbr: http://docs.openstack.org/developer/pbr/
 

doc/source/contributor/plugin/scoring-engine-plugin.rst

@@ -37,7 +37,8 @@ Create a new scoring engine plugin
 
 In order to create a new scoring engine you have to:
 
-- Extend the :py:class:`~.ScoringEngine` class
+- Extend the :py:class:`watcher.decision_engine.scoring.base.ScoringEngine`
+  class
 - Implement its :py:meth:`~.ScoringEngine.get_name` method to return the
   **unique** ID of the new scoring engine you want to create. This unique ID
   should be the same as the name of :ref:`the entry point we will declare later
@@ -124,7 +125,8 @@ scoring engine deployed as a web service on external servers:
 Abstract Plugin Class
 =====================
 
-Here below is the abstract :py:class:`~.ScoringEngine` class:
+Here below is the abstract
+:py:class:`watcher.decision_engine.scoring.base.ScoringEngine` class:
 
 .. autoclass:: watcher.decision_engine.scoring.base.ScoringEngine
     :members:

doc/source/glossary.rst

@@ -65,6 +65,14 @@ Audit
 
 .. _audit_template_definition:
 
+Audit Scope
+===========
+
+An Audit Scope is a set of audited resources. Audit Scope should be defined
+in each Audit Template (which contains the Audit settings).
+
+.. _audit_scope_definition:
+
 Audit Template
 ==============
 

doc/source/index.rst

@@ -77,11 +77,19 @@ Installation
 
   install/index
 
+Watcher Configuration Options
+=============================
+
+.. toctree::
+  :maxdepth: 2
+
+  configuration/index
+
 Admin Guide
 ===========
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
   admin/index
 

doc/source/man/index.rst

@@ -2,8 +2,6 @@
    :glob:
    :maxdepth: 1
 
-   footer.rst
-   general-options
    watcher-api
    watcher-applier
    watcher-db-manage

setup.cfg

@@ -109,6 +109,7 @@ source-dir = doc/source
 build-dir = doc/build
 fresh_env = 1
 all_files = 1
+warning-is-error = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html

tox.ini

@@ -44,7 +44,7 @@ commands = oslo_debug_helper -t watcher/tests {posargs}
 [testenv:genconfig]
 sitepackages = False
 commands =
-    oslo-config-generator --config-file etc/watcher/watcher-config-generator.conf
+    oslo-config-generator --config-file etc/watcher/oslo-config-generator/watcher.conf
 
 [flake8]
 show-source=True

watcher/api/controllers/v1/audit_template.py

@@ -550,7 +550,7 @@ class AuditTemplatesController(rest.RestController):
     def get_one(self, audit_template):
         """Retrieve information about the given audit template.
 
-        :param audit audit_template: UUID or name of an audit template.
+        :param audit_template: UUID or name of an audit template.
         """
         if self.from_audit_templates:
             raise exception.OperationNotPermitted
@@ -597,7 +597,7 @@ class AuditTemplatesController(rest.RestController):
     def patch(self, audit_template, patch):
         """Update an existing audit template.
 
-        :param audit template_uuid: UUID of a audit template.
+        :param template_uuid: UUID of a audit template.
         :param patch: a json PATCH document to apply to this audit template.
         """
         if self.from_audit_templates:
@@ -645,7 +645,7 @@ class AuditTemplatesController(rest.RestController):
     def delete(self, audit_template):
         """Delete a audit template.
 
-        :param audit template_uuid: UUID or name of an audit template.
+        :param template_uuid: UUID or name of an audit template.
         """
         context = pecan.request.context
         audit_template_to_delete = api_utils.get_resource('AuditTemplate',

watcher/conf/decision_engine.py

@@ -49,7 +49,7 @@ WATCHER_DECISION_ENGINE_OPTS = [
                     '-whose number of hours has been offset by this value-'
                     ' is older that the current time.'),
     cfg.IntOpt('check_periodic_interval',
-               default=30*60,
+               default=30 * 60,
                help='Interval (in seconds) for checking action plan expiry.')
 ]
 

watcher/decision_engine/planner/weight.py

@@ -19,7 +19,6 @@ import collections
 
 import networkx as nx
 from oslo_config import cfg
-from oslo_config import types
 from oslo_log import log
 
 from watcher.common import utils
@@ -69,17 +68,15 @@ class WeightPlanner(base.BasePlanner):
     @classmethod
     def get_config_opts(cls):
         return [
-            cfg.Opt(
+            cfg.DictOpt(
                 'weights',
-                type=types.Dict(value_type=types.Integer()),
                 help="These weights are used to schedule the actions. "
                      "Action Plan will be build in accordance with sets of "
                      "actions ordered by descending weights."
                      "Two action types cannot have the same weight. ",
                 default=cls.action_weights),
-            cfg.Opt(
+            cfg.DictOpt(
                 'parallelization',
-                type=types.Dict(value_type=types.Integer()),
                 help="Number of actions to be run in parallel on a per "
                      "action type basis.",
                 default=cls.parallelization),

watcher/decision_engine/planner/workload_stabilization.py

@@ -17,7 +17,6 @@
 import abc
 
 from oslo_config import cfg
-from oslo_config import types
 from oslo_log import log
 
 from watcher.common import clients
@@ -65,9 +64,8 @@ class WorkloadStabilizationPlanner(base.BasePlanner):
     @classmethod
     def get_config_opts(cls):
         return [
-            cfg.Opt(
+            cfg.DictOpt(
                 'weights',
-                type=types.Dict(value_type=types.Integer()),
                 help="These weights are used to schedule the actions",
                 default=cls.weights_dict),
         ]