Build docs with -W

This fixes all build warnings in the docs, and makes them build
with -W (consider warnings as errors).

Work items:

* Remove the useless "METRICS_CONF" global variable in the monasca collector.
  It was causing the "load_conf()" function to fail, as the
  /etc/cloudkitty/metrics.yml file couldn't be found.

* Change the docstring indentation in
  cloudkitty/rating/hash/controllers/mapping.py. This was the cause for the
  "doc/source/api-reference/v1/rating/hashmap.rst:12: WARNING: Field list ends
  without a blank line; unexpected unindent." message.

* Added a cloudkitty.conf sample to the admin documentation.

* Deleted unused files.

* Fixed the policy.yaml sample include path.

* Sorted the v2 API parameters alphabetically.

* Ignored the "wsmeext.sphinxext: directive 'autoattribute' is
  already registered" warning

* Added :noindex: directives to functions documented twice.

* Made sphinx always build with -W.

Change-Id: I5f1ab04e18920f3352c2807878cad327692a225f

cloudkitty/collector/monasca.py

@@ -53,8 +53,6 @@ CONF.register_opts(collector_monasca_opts, COLLECTOR_MONASCA_OPTS)
 ks_loading.register_auth_conf_options(CONF, COLLECTOR_MONASCA_OPTS)
 ks_loading.register_session_conf_options(CONF, COLLECTOR_MONASCA_OPTS)
 
-METRICS_CONF = ck_utils.load_conf(CONF.collect.metrics_conf)
-
 MONASCA_EXTRA_SCHEMA = {
     Required('extra_args', default={}): {
         # Key corresponding to the resource id in a metric's dimensions

cloudkitty/rating/hash/controllers/mapping.py

@@ -70,7 +70,8 @@ class HashMapMappingsController(rating.RatingRestControllerBase):
         :param no_group: Filter on orphaned mappings.
         :param tenant_id: Tenant UUID to filter on.
         :param filter_tenant: Explicitly filter on tenant (default is to not
-        filter on tenant). Useful if you want to filter on tenant being None.
+                              filter on tenant). Useful if you want to filter
+                              on tenant being None.
         :return: List of every mappings.
         """
         hashmap = db_api.get_instance()

cloudkitty/rating/hash/controllers/root.py

@@ -26,9 +26,7 @@ from cloudkitty.rating.hash.datamodels import mapping as mapping_models
 
 
 class HashMapConfigController(rating.RatingRestControllerBase):
-    """Controller exposing all management sub controllers.
+    """Controller exposing all management sub controllers."""
-
-    """
 
     _custom_actions = {
         'types': ['GET']

doc/source/admin/configuration/configuration.rst

@@ -2,6 +2,9 @@
 Step by step configuration guide
 ================================
 
+.. note:: For a sample ``cloudkitty.conf`` file, see
+          :doc:`samples/cloudkitty-conf` .
+
 Edit ``/etc/cloudkitty/cloudkitty.conf`` to configure cloudkitty.
 
 Common options

doc/source/admin/configuration/index.rst

@@ -9,4 +9,5 @@ Configuration Guide
    fetcher
    collector
    storage
+   samples/cloudkitty-conf
    policy

doc/source/admin/configuration/samples/cloudkitty-conf.rst

@@ -0,0 +1,5 @@
+=========================
+cloudkitty.conf reference
+=========================
+
+.. literalinclude:: ../../../_static/cloudkitty.conf.sample

doc/source/admin/configuration/samples/index.rst

@@ -1,11 +0,0 @@
-==========================
-Sample configuration files
-==========================
-
-Configuration files can alter how cloudkitty behaves at runtime and by default
-are located in ``/etc/cloudkitty/``. Links to sample configuration files can be
-found below:
-
-.. toctree::
-
-   policy-yaml.rst

doc/source/admin/configuration/samples/policy-yaml.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 policy.yaml
 ===========
@@ -5,4 +7,4 @@ policy.yaml
 Use the ``policy.yaml`` file to define additional access controls that apply to
 the Rating service:
 
-.. literalinclude:: ../../../_static/policy.yaml.sample
+.. literalinclude:: ../../../_static/cloudkitty.policy.yaml.sample

doc/source/admin/sample_policy.rst

@@ -1,16 +0,0 @@
-========================
-Cloudkitty Sample Policy
-========================
-
-The following is a sample Cloudkitty policy file that has been auto-generated
-from default policy values in code. If you're using the default policies, then
-the maintenance of this file is not necessary, and it should not be copied into
-a deployment. Doing so will result in duplicate policy definitions. It is here
-to help explain which policy operations protect specific Cloudkitty APIs, but
-it is not suggested to copy and paste into a deployment unless you're planning
-on providing a different policy for an operation that is not the default.
-
-The sample policy file can also be viewed in
-`file form <_static/policy.yaml.sample>`_.
-
-.. literalinclude:: _static/policy.yaml.sample

doc/source/api-reference/v2/dataframes/dataframes_parameters.yml

@@ -1,3 +1,38 @@
+begin:
+  in: query
+  description: |
+    Begin of the period for which the dataframes are required.
+  type: iso8601 timestamp
+  required: false
+
+end:
+  in: query
+  description: |
+    End of the period for which the dataframes are required.
+  type: iso8601 timestamp
+  required: false
+
+filters:
+  in: query
+  description: |
+    Optional filters.
+  type: dict
+  required: false
+
+limit:
+  in: query
+  description: |
+    For pagination. The maximum number of results to return.
+  type: int
+  required: false
+
+offset:
+  in: query
+  description: |
+    For pagination. The index of the first element that should be returned.
+  type: int
+  required: false
+
 dataframes_body:
   in: body
   description: |
@@ -18,38 +53,3 @@ total_resp:
     Total of datapoints matching the query parameters.
   type: int
   required: true
-
-limit:
-  in: query
-  description: |
-    For pagination. The maximum number of results to return.
-  type: int
-  required: false
-
-offset:
-  in: query
-  description: |
-    For pagination. The index of the first element that should be returned.
-  type: int
-  required: false
-
-filters:
-  in: query
-  description: |
-    Optional filters.
-  type: dict
-  required: false
-
-begin:
-  in: query
-  description: |
-    Begin of the period for which the dataframes are required.
-  type: iso8601 timestamp
-  required: false
-
-end:
-  in: query
-  description: |
-    End of the period for which the dataframes are required.
-  type: iso8601 timestamp
-  required: false

doc/source/api-reference/v2/scope/scope_parameters.yml

@@ -1,3 +1,17 @@
+collector: &collector
+  in: query
+  description: |
+    Filter on collector.
+  type: string
+  required: false
+
+fetcher: &fetcher
+  in: query
+  description: |
+    Filter on fetcher.
+  type: string
+  required: false
+
 limit:
   in: query
   description: |
@@ -19,20 +33,6 @@ scope_id: &scope_id
   type: string
   required: false
 
-fetcher: &fetcher
-  in: query
-  description: |
-    Filter on fetcher.
-  type: string
-  required: false
-
-collector: &collector
-  in: query
-  description: |
-    Filter on collector.
-  type: string
-  required: false
-
 scope_key: &scope_key
   in: query
   description: |
@@ -46,23 +46,8 @@ all_scopes: &all_scopes
     Confirmation whether all scopes must be reset
   type: bool
 
-state:
+collector_body:
-  in: body
+  <<: *collector
-  description: |
-    State of the scope.
-  type: iso8601 timestamp
-  required: true
-
-fetcher_resp:
-  <<: *fetcher
-  required: true
-  description: Fetcher for the given scope
-  in: body
-
-scope_id_resp:
-  <<: *scope_id
-  required: true
-  description: Scope
   in: body
 
 collector_resp:
@@ -71,24 +56,39 @@ collector_resp:
   description: Collector for the given scope
   in: body
 
-scope_key_resp:
-  <<: *scope_key
-  required: true
-  description: Scope key for the given scope
-  in: body
-
-collector_body:
-  <<: *collector
-  in: body
-
 fetcher_body:
   <<: *fetcher
   in: body
 
+fetcher_resp:
+  <<: *fetcher
+  required: true
+  description: Fetcher for the given scope
+  in: body
+
 scope_id_body:
   <<: *scope_id
   in: body
 
+scope_id_resp:
+  <<: *scope_id
+  required: true
+  description: Scope
+  in: body
+
 scope_key_body:
   <<: *scope_key
   in: body
+
+scope_key_resp:
+  <<: *scope_key
+  required: true
+  description: Scope key for the given scope
+  in: body
+
+state:
+  in: body
+  description: |
+    State of the scope.
+  type: iso8601 timestamp
+  required: true

doc/source/api-reference/v2/summary/summary_parameters.yml

@@ -1,15 +1,15 @@
-limit:
+begin: &begin
   in: query
   description: |
-    For pagination. The maximum number of results to return.
+    Begin of the period for which the summary is required.
-  type: int
+  type: iso8601 timestamp
   required: false
 
-offset: &offset
+end: &end
   in: query
   description: |
-    For pagination. The index of the first element that should be returned.
+    End of the period for which the summary is required.
-  type: int
+  type: iso8601 timestamp
   required: false
 
 filters:
@@ -26,34 +26,20 @@ groupby:
   type: list of strings
   required: false
 
-begin: &begin
+limit:
   in: query
   description: |
-    Begin of the period for which the summary is required.
+    For pagination. The maximum number of results to return.
-  type: iso8601 timestamp
+  type: int
   required: false
 
-end: &end
+offset: &offset
   in: query
   description: |
-    End of the period for which the summary is required.
+    For pagination. The index of the first element that should be returned.
-  type: iso8601 timestamp
+  type: int
   required: false
 
-qty: &qty
-  in: body
-  description: |
-    Qty for the item.
-  type: float
-  required: true
-
-rate: &rate
-  in: body
-  description: |
-    Rate for the item.
-  type: float
-  required: true
-
 begin_resp:
   <<: *begin
   required: true
@@ -66,12 +52,26 @@ end_resp:
   description: End of the period for the item.
   in: body
 
+qty: &qty
+  in: body
+  description: |
+    Qty for the item.
+  type: float
+  required: true
+
 qty_resp:
   <<: *qty
   required: true
   description: Qty for the item in the specified period.
   in: body
 
+rate: &rate
+  in: body
+  description: |
+    Rate for the item.
+  type: float
+  required: true
+
 rate_resp:
   <<: *rate
   required: true

doc/source/conf.py

@@ -57,13 +57,19 @@ extensions = ['sphinx.ext.coverage',
               'oslo_policy.sphinxpolicygen',
               ]
 
+# Ignore the following warning: WARNING: while setting up extension
+# wsmeext.sphinxext: directive 'autoattribute' is already registered,
+# it will be overridden.
+suppress_warnings = ['app.add_directive']
+
 # openstackdocstheme options
 repository_name = 'openstack/cloudkitty'
 bug_project = 'cloudkitty'
 bug_tag = ''
 
+config_generator_config_file = '../../etc/oslo-config-generator/cloudkitty.conf'
 policy_generator_config_file = '../../etc/oslo-policy-generator/cloudkitty.conf'
-sample_policy_basename = '_static/cloudkitty'
+sample_policy_basename = sample_config_basename = '_static/cloudkitty'
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = []

doc/source/developer/api/tutorial.rst

@@ -72,6 +72,7 @@ example endpoint"}**. The ``add_output_schema`` decorator adds voluptuous
 validation to a method's output. This allows to set defaults.
 
 .. autofunction:: cloudkitty.api.v2.utils.add_output_schema
+   :noindex:
 
 Let's update our ``get`` method in order to use this decorator:
 
@@ -108,6 +109,7 @@ parameter. In order to validate it, we'll use the ``add_input_schema``
 decorator:
 
 .. autofunction:: cloudkitty.api.v2.utils.add_input_schema
+   :noindex:
 
 Arguments validated by the input schema are passed as named arguments to the
 decorated function. Let's implement the post method. We'll use Werkzeug
@@ -157,6 +159,7 @@ query parameters as lists. The ``SingleQueryParam`` helper checks that a
 parameter is provided only once, and returns it.
 
 .. autoclass:: cloudkitty.api.v2.utils.SingleQueryParam
+   :noindex:
 
 .. warning:: ``SingleQueryParam`` uses ``voluptuous.Coerce`` internally for
              type checking. Thus, ``validation_utils.get_string_type`` cannot
@@ -274,6 +277,7 @@ Each endpoint should provide an ``init`` method taking a Flask app as only
 parameter. This method should call ``do_init``:
 
 .. autofunction:: cloudkitty.api.v2.utils.do_init
+   :noindex:
 
 Add the following to ``cloudkitty/api/v2/example/__init__.py``:
 

doc/source/pdf-index.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 ======================================
 Welcome to CloudKitty's documentation!
 ======================================

tox.ini

@@ -49,14 +49,14 @@ commands =
 commands = oslopolicy-sample-generator --config-file=etc/oslo-policy-generator/cloudkitty.conf
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:pdf-docs]
 envdir = {toxworkdir}/docs
 whitelist_externals =
   make
 commands =
-  sphinx-build -b latex doc/source doc/build/pdf
+  sphinx-build -W -b latex doc/source doc/build/pdf
   make -C doc/build/pdf
 
 [testenv:venv]