Enforce doc8, make it pass, + fix inaccuracies
This patch fixes all sphinx warnings generated by malformed docstrings. Additionally, it contains formatting and accuracy fixes for the metrics docstrings, to ensure blockquotes are properly rendered, and to indicate the get_metrics_logger() method is actually in metrics_utils. Finally, this adds doc8 to the pep8 job, ensuring we don't reintroduce some of these errors. As a note, there are items that can cause warnings in doc builds that aren't enforced by doc8, and can't be enforced until a doc build job is added to project-config. Change-Id: I622812bfe8af576ab215c098dd211c6faf697a0c Partial-bug: #1614272 Partial-bug: #1611559
This commit is contained in:
Jay Faulkner
parent
4f58317ce0
commit
84f8c3095a
|
|
@ -109,7 +109,7 @@ def get_disk_identifier(dev):
|
|||
http://www.syslinux.org/wiki/index.php/Comboot/chain.c32#mbr:
|
||||
|
||||
:param dev: Path for the already populated disk device.
|
||||
:returns The Disk Identifier.
|
||||
:returns: The Disk Identifier.
|
||||
"""
|
||||
disk_identifier = utils.execute('hexdump', '-s', '440', '-n', '4',
|
||||
'-e', '''\"0x%08x\"''',
|
||||
|
|
@ -434,9 +434,9 @@ def work_on_disk(dev, root_mb, swap_mb, ephemeral_mb, ephemeral_format,
|
|||
:returns: a dictionary containing the following keys:
|
||||
'root uuid': UUID of root partition
|
||||
'efi system partition uuid': UUID of the uefi system partition
|
||||
(if boot mode is uefi).
|
||||
(if boot mode is uefi).
|
||||
NOTE: If key exists but value is None, it means partition doesn't
|
||||
exist.
|
||||
exist.
|
||||
"""
|
||||
# the only way for preserve_ephemeral to be set to true is if we are
|
||||
# rebuilding an instance with --preserve_ephemeral.
|
||||
|
|
|
|||
|
|
@ -26,18 +26,20 @@ from ironic_lib.common.i18n import _
|
|||
class Timer(object):
|
||||
"""A timer decorator and context manager.
|
||||
|
||||
It is bound to this MetricLogger. For example:
|
||||
This metric type times the decorated method or code running inside the
|
||||
context manager, and emits the time as the metric value. It is bound to
|
||||
this MetricLogger. For example::
|
||||
|
||||
from ironic_lib import metrics
|
||||
from ironic_lib import metrics_utils
|
||||
|
||||
METRICS = metrics.get_metrics_logger()
|
||||
METRICS = metrics_utils.get_metrics_logger()
|
||||
|
||||
@METRICS.timer('foo')
|
||||
def foo(bar, baz):
|
||||
print bar, baz
|
||||
@METRICS.timer('foo')
|
||||
def foo(bar, baz):
|
||||
print bar, baz
|
||||
|
||||
with METRICS.timer('foo'):
|
||||
do_something()
|
||||
with METRICS.timer('foo'):
|
||||
do_something()
|
||||
"""
|
||||
def __init__(self, metrics, name):
|
||||
"""Init the decorator / context manager.
|
||||
|
|
@ -78,18 +80,20 @@ class Timer(object):
|
|||
class Counter(object):
|
||||
"""A counter decorator and context manager.
|
||||
|
||||
It is bound to this MetricLogger. For example:
|
||||
This metric type increments a counter every time the decorated method or
|
||||
context manager is executed. It is bound to this MetricLogger. For
|
||||
example::
|
||||
|
||||
from ironic_lib import metrics
|
||||
from ironic_lib import metrics_utils
|
||||
|
||||
METRICS = metrics.get_metrics_logger()
|
||||
METRICS = metrics_utils.get_metrics_logger()
|
||||
|
||||
@METRICS.counter('foo')
|
||||
def foo(bar, baz):
|
||||
print bar, baz
|
||||
@METRICS.counter('foo')
|
||||
def foo(bar, baz):
|
||||
print bar, baz
|
||||
|
||||
with METRICS.counter('foo'):
|
||||
do_something()
|
||||
with METRICS.counter('foo'):
|
||||
do_something()
|
||||
"""
|
||||
def __init__(self, metrics, name, sample_rate):
|
||||
"""Init the decorator / context manager.
|
||||
|
|
@ -135,18 +139,17 @@ class Counter(object):
|
|||
class Gauge(object):
|
||||
"""A gauge decorator.
|
||||
|
||||
It is bound to this MetricLogger. For example:
|
||||
This metric type returns the value of the decorated method as a metric
|
||||
every time the method is executed. It is bound to this MetricLogger. For
|
||||
example::
|
||||
|
||||
from ironic_lib import metrics
|
||||
from ironic_lib import metrics_utils
|
||||
|
||||
METRICS = metrics.get_metrics_logger()
|
||||
METRICS = metrics_utils.get_metrics_logger()
|
||||
|
||||
@METRICS.gauge('foo')
|
||||
def foo(bar, baz):
|
||||
print bar, baz
|
||||
|
||||
with METRICS.gauge('foo'):
|
||||
do_something()
|
||||
@METRICS.gauge('foo')
|
||||
def add_foo(bar, baz):
|
||||
return (bar + baz)
|
||||
"""
|
||||
def __init__(self, metrics, name):
|
||||
"""Init the decorator / context manager.
|
||||
|
|
@ -184,15 +187,15 @@ class MetricLogger(object):
|
|||
The data can be a gauge, a counter, or a timer.
|
||||
|
||||
The data sent to the backend is composed of:
|
||||
- a full metric name
|
||||
- a numeric value
|
||||
- a full metric name
|
||||
- a numeric value
|
||||
|
||||
The format of the full metric name is:
|
||||
_prefix<delim>name
|
||||
where:
|
||||
_prefix: [global_prefix<delim>][uuid<delim>][host_name<delim>]prefix
|
||||
name: the name of this metric
|
||||
<delim>: the delimiter. Default is '.'
|
||||
- _prefix: [global_prefix<delim>][uuid<delim>][host_name<delim>]prefix
|
||||
- name: the name of this metric
|
||||
- <delim>: the delimiter. Default is '.'
|
||||
"""
|
||||
|
||||
def __init__(self, prefix='', delimiter='.'):
|
||||
|
|
@ -211,9 +214,11 @@ class MetricLogger(object):
|
|||
The format of the full metric name is:
|
||||
_prefix<delim>name
|
||||
where:
|
||||
_prefix: [global_prefix<delim>][uuid<delim>][host_name<delim>]prefix
|
||||
name: the name of this metric
|
||||
<delim>: the delimiter. Default is '.'
|
||||
- _prefix: [global_prefix<delim>][uuid<delim>][host_name<delim>]
|
||||
prefix
|
||||
- name: the name of this metric
|
||||
- <delim>: the delimiter. Default is '.'
|
||||
|
||||
|
||||
:param name: The metric name.
|
||||
:return: The full metric name, with logger prefix, as a string.
|
||||
|
|
@ -240,7 +245,7 @@ class MetricLogger(object):
|
|||
The backend will increment the counter 'name' by the value 'value'.
|
||||
|
||||
Optionally, specify sample_rate in the interval [0.0, 1.0] to
|
||||
sample data probabilistically where:
|
||||
sample data probabilistically where::
|
||||
|
||||
P(send metric data) = sample_rate
|
||||
|
||||
|
|
|
|||
|
|
@ -12,5 +12,6 @@ testscenarios>=0.4 # Apache-2.0/BSD
|
|||
testtools>=1.4.0 # MIT
|
||||
|
||||
# Doc requirements
|
||||
doc8 # Apache-2.0
|
||||
sphinx!=1.3b1,<1.3,>=1.2.1 # BSD
|
||||
oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
|
||||
|
|
|
|||
Loading…
Reference in New Issue