From 84f8c3095a23dc1f3e2ffa0cff25380a9945da51 Mon Sep 17 00:00:00 2001 From: Jay Faulkner Date: Wed, 17 Aug 2016 15:41:18 -0700 Subject: [PATCH] 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 --- ironic_lib/disk_utils.py | 6 ++-- ironic_lib/metrics.py | 73 +++++++++++++++++++++------------------- test-requirements.txt | 1 + tox.ini | 4 ++- 4 files changed, 46 insertions(+), 38 deletions(-) diff --git a/ironic_lib/disk_utils.py b/ironic_lib/disk_utils.py index d7a02040..1c2f906f 100644 --- a/ironic_lib/disk_utils.py +++ b/ironic_lib/disk_utils.py @@ -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. diff --git a/ironic_lib/metrics.py b/ironic_lib/metrics.py index 20c85321..889ca33d 100644 --- a/ironic_lib/metrics.py +++ b/ironic_lib/metrics.py @@ -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: _prefixname where: - _prefix: [global_prefix][uuid][host_name]prefix - name: the name of this metric - : the delimiter. Default is '.' + - _prefix: [global_prefix][uuid][host_name]prefix + - name: the name of this metric + - : the delimiter. Default is '.' """ def __init__(self, prefix='', delimiter='.'): @@ -211,9 +214,11 @@ class MetricLogger(object): The format of the full metric name is: _prefixname where: - _prefix: [global_prefix][uuid][host_name]prefix - name: the name of this metric - : the delimiter. Default is '.' + - _prefix: [global_prefix][uuid][host_name] + prefix + - name: the name of this metric + - : 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 diff --git a/test-requirements.txt b/test-requirements.txt index eb64ecf3..b6f0e36b 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -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 diff --git a/tox.ini b/tox.ini index 8759b9d4..6ff721ff 100644 --- a/tox.ini +++ b/tox.ini @@ -18,7 +18,9 @@ ignore = E129 exclude = .venv,.tox,dist,doc,*.egg,.update-venv [testenv:pep8] -commands = flake8 {posargs} +commands = + flake8 {posargs} + doc8 README.rst doc/source --ignore D001 [testenv:cover] setenv = VIRTUALENV={envdir}