Merge "Enforce doc8, make it pass, + fix inaccuracies"

ironic_lib/disk_utils.py

@@ -115,7 +115,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\"''',
@@ -440,9 +440,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.

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:
         _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
 

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

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}