openstack/cloudkitty
Code Issues Proposed changes

Build docs with -W

Browse Source 
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
This commit is contained in:
Luka Peschke
2019-11-21 17:01:17 +01:00
parent 4b00816db2
commit 3426a6648a
17 changed files with 1519 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
cloudkitty/collector/monasca.py
View File

@@ -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

3
cloudkitty/rating/hash/controllers/mapping.py
View File

@@ -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()

4
cloudkitty/rating/hash/controllers/root.py
View File

@@ -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']

1387
doc/source/_static/cloudkitty.conf.sample Normal file
View File

File diff suppressed because it is too large Load Diff

3
doc/source/admin/configuration/configuration.rst
View File

@@ -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

1
doc/source/admin/configuration/index.rst
View File

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

5
doc/source/admin/configuration/samples/cloudkitty-conf.rst Normal file
View File

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

11
doc/source/admin/configuration/samples/index.rst
View File

@@ -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

4
doc/source/admin/configuration/samples/policy-yaml.rst
View File

@@ -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

16
doc/source/admin/sample_policy.rst
View File

@@ -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

70
doc/source/api-reference/v2/dataframes/dataframes_parameters.yml
View File

@@ -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

82
doc/source/api-reference/v2/scope/scope_parameters.yml
View File

@@ -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:
in: body
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
collector_body:
<<: *collector
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

52
doc/source/api-reference/v2/summary/summary_parameters.yml
View File

@@ -1,15 +1,15 @@
limit:
begin: &begin
in: query
description: |
For pagination. The maximum number of results to return.
type: int
Begin of the period for which the summary is required.
type: iso8601 timestamp
required: false
offset: &offset
end: &end
in: query
description: |
For pagination. The index of the first element that should be returned.
type: int
End of the period for which the summary is required.
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.
type: iso8601 timestamp
For pagination. The maximum number of results to return.
type: int
required: false
end: &end
offset: &offset
in: query
description: |
End of the period for which the summary is required.
type: iso8601 timestamp
For pagination. The index of the first element that should be returned.
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

8
doc/source/conf.py
View File

@@ -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 = []

4
doc/source/developer/api/tutorial.rst
View File

@@ -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``:

2
doc/source/pdf-index.rst
View File

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

4
tox.ini
View File

@@ -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]