From 8fd57276be35ba784b174e00cdde372eda2fb44b Mon Sep 17 00:00:00 2001 From: Alexander Chadin Date: Mon, 24 Jul 2017 16:36:41 +0300 Subject: [PATCH] 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 | 2 +- doc/source/_static/.placeholder | 0 doc/source/admin/conf-files.rst | 14 -------------- doc/source/admin/index.rst | 2 -- doc/source/admin/ways-to-install.rst | 11 ++++++----- doc/source/conf.py | 11 ++++++++--- doc/source/config-generator.conf | 1 - .../configuring.rst} | 0 doc/source/configuration/index.rst | 5 +++++ doc/source/configuration/watcher.rst | 11 +++++++++++ doc/source/contributor/environment.rst | 4 ++-- doc/source/contributor/index.rst | 10 +++++----- doc/source/contributor/plugin/goal-plugin.rst | 5 +++-- .../contributor/plugin/scoring-engine-plugin.rst | 6 ++++-- doc/source/glossary.rst | 8 ++++++++ doc/source/index.rst | 10 +++++++++- doc/source/man/index.rst | 2 -- .../watcher.conf} | 0 setup.cfg | 1 + tox.ini | 2 +- watcher/api/controllers/v1/audit_template.py | 6 +++--- watcher/conf/decision_engine.py | 2 +- watcher/decision_engine/planner/weight.py | 7 ++----- .../planner/workload_stabilization.py | 4 +--- 24 files changed, 71 insertions(+), 53 deletions(-) create mode 100644 doc/source/_static/.placeholder delete mode 100644 doc/source/admin/conf-files.rst delete mode 100644 doc/source/config-generator.conf rename doc/source/{admin/configuration.rst => configuration/configuring.rst} (100%) create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/watcher.rst rename etc/watcher/{watcher-config-generator.conf => oslo-config-generator/watcher.conf} (100%) diff --git a/.gitignore b/.gitignore index debf764ed..6e4c388b2 100644 --- a/.gitignore +++ b/.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 diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/admin/conf-files.rst b/doc/source/admin/conf-files.rst deleted file mode 100644 index 792bc2ccd..000000000 --- a/doc/source/admin/conf-files.rst +++ /dev/null @@ -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 diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 62729ead0..ffba20c5e 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -6,8 +6,6 @@ Administrator Guide :maxdepth: 2 apache-mod-wsgi - conf-files - configuration gmr policy ways-to-install diff --git a/doc/source/admin/ways-to-install.rst b/doc/source/admin/ways-to-install.rst index 43bd88894..52518de61 100644 --- a/doc/source/admin/ways-to-install.rst +++ b/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) diff --git a/doc/source/conf.py b/doc/source/conf.py index b73eca8f1..f448e82d1 100755 --- a/doc/source/conf.py +++ b/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' diff --git a/doc/source/config-generator.conf b/doc/source/config-generator.conf deleted file mode 100644 index e704259f1..000000000 --- a/doc/source/config-generator.conf +++ /dev/null @@ -1 +0,0 @@ -../../etc/watcher/watcher-config-generator.conf diff --git a/doc/source/admin/configuration.rst b/doc/source/configuration/configuring.rst similarity index 100% rename from doc/source/admin/configuration.rst rename to doc/source/configuration/configuring.rst diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 000000000..fe3b95881 --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,5 @@ +.. toctree:: + :maxdepth: 1 + + configuring + watcher diff --git a/doc/source/configuration/watcher.rst b/doc/source/configuration/watcher.rst new file mode 100644 index 000000000..ddca6c8d5 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/environment.rst b/doc/source/contributor/environment.rst index 3c7545a31..80db88f4e 100644 --- a/doc/source/contributor/environment.rst +++ b/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. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index eddf972d4..d8985942b 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,8 +1,8 @@ .. toctree:: :maxdepth: 1 - environment - devstack - notifications - testing - rally_link + environment + devstack + notifications + testing + rally_link diff --git a/doc/source/contributor/plugin/goal-plugin.rst b/doc/source/contributor/plugin/goal-plugin.rst index f0e7dd8ad..0a43c04d6 100644 --- a/doc/source/contributor/plugin/goal-plugin.rst +++ b/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/ diff --git a/doc/source/contributor/plugin/scoring-engine-plugin.rst b/doc/source/contributor/plugin/scoring-engine-plugin.rst index 728fbcfb4..babc2dfe0 100644 --- a/doc/source/contributor/plugin/scoring-engine-plugin.rst +++ b/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: diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst index 7ab060202..d4c466772 100644 --- a/doc/source/glossary.rst +++ b/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 ============== diff --git a/doc/source/index.rst b/doc/source/index.rst index 16e258e16..15b4f5504 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/doc/source/man/index.rst b/doc/source/man/index.rst index 74469af1a..09a408d91 100644 --- a/doc/source/man/index.rst +++ b/doc/source/man/index.rst @@ -2,8 +2,6 @@ :glob: :maxdepth: 1 - footer.rst - general-options watcher-api watcher-applier watcher-db-manage diff --git a/etc/watcher/watcher-config-generator.conf b/etc/watcher/oslo-config-generator/watcher.conf similarity index 100% rename from etc/watcher/watcher-config-generator.conf rename to etc/watcher/oslo-config-generator/watcher.conf diff --git a/setup.cfg b/setup.cfg index 3f6ed1dd3..34c93e344 100644 --- a/setup.cfg +++ b/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 diff --git a/tox.ini b/tox.ini index 89148b25c..aa2bedaab 100644 --- a/tox.ini +++ b/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 diff --git a/watcher/api/controllers/v1/audit_template.py b/watcher/api/controllers/v1/audit_template.py index b85e2f28a..4f673c61e 100644 --- a/watcher/api/controllers/v1/audit_template.py +++ b/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', diff --git a/watcher/conf/decision_engine.py b/watcher/conf/decision_engine.py index 162dc29d4..f2ceb3a38 100644 --- a/watcher/conf/decision_engine.py +++ b/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.') ] diff --git a/watcher/decision_engine/planner/weight.py b/watcher/decision_engine/planner/weight.py index 24c707a6d..7c2fce037 100644 --- a/watcher/decision_engine/planner/weight.py +++ b/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), diff --git a/watcher/decision_engine/planner/workload_stabilization.py b/watcher/decision_engine/planner/workload_stabilization.py index f7cd96afa..372c5e3bb 100644 --- a/watcher/decision_engine/planner/workload_stabilization.py +++ b/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), ]