Add doc8 to pep8 check for ceilometer project

This patch adds a doc8 check of .rst files to the current pep8 check.
It includes fixes to the .rst files that didn't pass the check.

Change-Id: If159ab37e2f59d7fe9ee1d7c3ebf0f62f030c87f
Co-authored-By: Hoang Trung Hieu <hieuht@vn.fujitsu.com>

doc/source/admin/telemetry-data-pipelines.rst

@@ -296,9 +296,7 @@ Multi meter arithmetic transformer
 ``````````````````````````````````
 
 This transformer enables us to perform arithmetic calculations over one
-or more meters and/or their metadata, for example:
+or more meters and/or their metadata, for example::
-
-.. code-block:: none
 
    memory_util = 100 * memory.usage / memory
 

doc/source/configuration/index.rst

@@ -17,8 +17,8 @@ can be easily created by running::
         --config-file=/etc/ceilometer/ceilometer-config-generator.conf \
         --output-file=/etc/ceilometer/ceilometer.conf
 
-The following is a sample Ceilometer configuration for adaptation and use. It is
+The following is a sample Ceilometer configuration for adaptation and use.
-auto-generated from Ceilometer when this documentation is built, and can also be
+It is auto-generated from Ceilometer when this documentation is built, and
-viewed in `file form <_static/ceilometer.conf.sample>`_.
+can also be viewed in `file form <_static/ceilometer.conf.sample>`_.
 
 .. literalinclude:: ../_static/ceilometer.conf.sample

doc/source/contributor/architecture.rst

@@ -27,8 +27,8 @@ workers and nodes can be added depending on the expected load. Ceilometer
 offers two core services:
 
 1. polling agent - daemon designed to poll OpenStack services and build Meters.
-2. notification agent - daemon designed to listen to notifications on message queue,
+2. notification agent - daemon designed to listen to notifications on message
-   convert them to Events and Samples, and apply pipeline actions.
+   queue, convert them to Events and Samples, and apply pipeline actions.
 
 Data normalised and collected by Ceilometer can be sent to various targets.
 Gnocchi_ was developed to capture measurement data in a time series format to
@@ -96,12 +96,12 @@ but by default, will listen to ``notifications.info``,
 messages off the configured topics and redistributes them to the appropriate
 plugins(endpoints) to be processed into Events and Samples.
 
-Sample-oriented plugins provide a method to list the event types they're interested
+Sample-oriented plugins provide a method to list the event types they're
-in and a callback for processing messages accordingly. The registered name of the
+interested in and a callback for processing messages accordingly.
-callback is used to enable or disable it using the pipeline of the notification
+The registered name of the callback is used to enable or disable it using
-daemon. The incoming messages are filtered based on their event type value before
+the pipeline of the notification daemon. The incoming messages are filtered
-being passed to the callback so the plugin only receives events it has
+based on their event type value before being passed to the callback so the
-expressed an interest in seeing.
+plugin only receives events it has expressed an interest in seeing.
 
 .. _polling:
 
@@ -188,8 +188,8 @@ Publishing the data
 Currently, processed data can be published using 7 different transports:
 
 1. gnocchi, which publishes samples/events to Gnocchi API;
-2. notifier, a notification based publisher which pushes samples to a message queue
+2. notifier, a notification based publisher which pushes samples to a message
-   which can be consumed by an external system;
+   queue which can be consumed by an external system;
 3. udp, which publishes samples using UDP packets;
 4. http, which targets a REST interface;
 5. file, which publishes samples to a file with specified name and location;

doc/source/contributor/configuration.rst

@@ -174,8 +174,8 @@ data should be sent after the possible transformations. The names of the
 publishers should be the same as the related names of the plugins in
 :file:`setup.cfg`.
 
-The default configuration can be found in `pipeline.yaml`_. For more details about
+The default configuration can be found in `pipeline.yaml`_. For more details
-how to configure publishers, see :ref:`publisher-configuration`.
+about how to configure publishers, see :ref:`publisher-configuration`.
 
 .. _pipeline.yaml: https://git.openstack.org/cgit/openstack/ceilometer/tree/ceilometer/pipeline/data/pipeline.yaml
 

doc/source/contributor/install/custom.rst

@@ -30,9 +30,9 @@ this queue. If you want to also consume the topic notifications with a system
 other than Ceilometer, you should configure a separate queue that listens for
 the same messages.
 
-Ceilometer allows multiple topics to be configured so that the polling agent can
+Ceilometer allows multiple topics to be configured so that the polling agent
-send the same messages of notifications to other queues. Notification agents
+can send the same messages of notifications to other queues. Notification
-also use **topics** to configure which queue to listen for. If
+agents also use **topics** to configure which queue to listen for. If
 you use multiple topics, you should configure notification agent and polling
 agent separately, otherwise Ceilometer collects duplicate samples.
 
@@ -45,7 +45,7 @@ To use multiple topics, you should give ceilometer-agent-notification and
 ceilometer-polling services different ceilometer.conf files. The Ceilometer
 configuration file ceilometer.conf is normally locate in the /etc/ceilometer
 directory. Make changes according to your requirements which may look like
-the following::
+the following:
 
 For notification agent using ceilometer-notification.conf, settings like::
 
@@ -62,7 +62,8 @@ For polling agent using ceilometer-polling.conf, settings like::
    notification_topics in ceilometer-notification.conf should only have one same
    topic in ceilometer-polling.conf
 
-Doing this, it's easy to listen/receive data from multiple internal and external services.
+Doing this, it's easy to listen/receive data from multiple internal and
+external services.
 
 ..  _publisher-configuration:
 
@@ -96,8 +97,8 @@ For the Gnocchi publisher, the archive policy can be defined as a configuration
 settings. The value specified for ``archive_policy`` should correspond to the
 name of an ``archive_policy`` configured within Gnocchi.
 
-To use multiple publishers, add multiple publisher lines in ``pipeline.yaml`` and/or
+To use multiple publishers, add multiple publisher lines in ``pipeline.yaml``
-``event_pipeline.yaml`` file like the following::
+and/or ``event_pipeline.yaml`` file like the following::
 
    ---
    sources:
@@ -124,12 +125,13 @@ configuration settings should be added::
 Custom pipeline
 ===============
 
-The paths of all pipeline files including ``pipeline.yaml`` and ``event_pipeline.yaml``
+The paths of all pipeline files including ``pipeline.yaml`` and
-are located to ceilometer/pipeline/data by default. And it's possible to set the
+``event_pipeline.yaml`` are located to ceilometer/pipeline/data by default.
-path through ``pipeline_cfg_file`` being assigned to another one in ``ceilometer.conf``.
+And it's possible to set the path through
+``pipeline_cfg_file`` being assigned to another one in ``ceilometer.conf``.
 
-Ceilometer allow users to customize pipeline files. Before that, copy the following
+Ceilometer allow users to customize pipeline files. Before that, copy the
-yaml files::
+following yaml files::
 
     $ cp ceilometer/pipeline/data/*.yaml /etc/ceilometer
 

doc/source/contributor/install/upgrade.rst

@@ -76,10 +76,10 @@ version in time.
 3. Upgrade the notification agent(s)
 
    The new notification agent can be started alongside the old agent if no
-   workload_partitioning is enabled OR if it has the same pipeline configuration.
+   workload_partitioning is enabled OR if it has the same pipeline
-   If the pipeline configuration is changed, the old agents must be loaded with
+   configuration. If the pipeline configuration is changed, the old agents
-   the same pipeline configuration first to ensure the notification agents all
+   must be loaded with the same pipeline configuration first to ensure the
-   work against same pipeline sets.
+   notification agents all work against same pipeline sets.
 
 4. Upgrade the polling agent(s)
 
@@ -100,5 +100,5 @@ version in time.
 Developer notes
 ===============
 
-When updating data models in the database or IPC, we need to adhere to a single
+When updating data models in the database or IPC, we need to adhere to
-mantra: 'always add, never delete or modify.'
+a single mantra: 'always add, never delete or modify.'

doc/source/contributor/measurements.rst

@@ -47,13 +47,14 @@ Three type of meters are defined in Ceilometer:
    double: meter; gauge
    double: meter; delta
 
-==========  ==============================================================================
+==========  ===================================================================
 Type        Definition
-==========  ==============================================================================
+==========  ===================================================================
 Cumulative  Increasing over time (instance hours)
-Gauge       Discrete items (floating IPs, image uploads) and fluctuating values (disk I/O)
+Gauge       Discrete items (floating IPs, image uploads) and fluctuating values
+            (disk I/O)
 Delta       Changing over time (bandwidth)
-==========  ==============================================================================
+==========  ===================================================================
 
 When you're about to add a new meter choose one type from the above list, which
 is applicable.
@@ -90,8 +91,9 @@ If you plan on adding meters, please follow the convention below:
 1. Always use '.' as separator and go from least to most discriminant word.
    For example, do not use ephemeral_disk_size but disk.ephemeral.size
 
-2. When a part of the name is a variable, it should always be at the end and start with a ':'.
+2. When a part of the name is a variable, it should always be at the end and
-   For example, do not use <type>.image but image:<type>, where type is your variable name.
+   start with a ':'. For example, do not use <type>.image but image:<type>,
+   where type is your variable name.
 
 3. If you have any hesitation, come and ask in #openstack-telemetry
 

doc/source/contributor/new_resource_types.rst

@@ -30,16 +30,17 @@
 Managing Resource Types
 =======================
 
-Resource types in Gnocchi are managed by Ceilometer. The following describes how to add/remove
+Resource types in Gnocchi are managed by Ceilometer. The following describes
-or update Gnocchi resource types to support new Ceilometer data.
+how to add/remove or update Gnocchi resource types to support new Ceilometer
+data.
 
 The modification or creation of Gnocchi resource type definitions are managed
 :section:`resources_update_operations` of :file:`ceilometer/gnocchi_client.py`.
 
 The following operations are supported:
 
-1. Adding a new attribute to a resource type. The following adds `flavor_name` attribute
+1. Adding a new attribute to a resource type. The following adds `flavor_name`
-   to an existing `instance` resource:
+   attribute to an existing `instance` resource:
 
 .. code::
 
@@ -53,8 +54,8 @@ The following operations are supported:
                    "required": True, "options": {'fill': ''}}
      }]}
 
-2. Remove an existing attribute from a resource type. The following removes `server_group`
+2. Remove an existing attribute from a resource type. The following removes
-   attribute from `instance` resource:
+   `server_group` attribute from `instance` resource:
 
 .. code::
 
@@ -66,8 +67,8 @@ The following operations are supported:
          "path": "/attributes/server_group"
      }]}
 
-3. Creating a new resource type. The following creates a new resource type named
+3. Creating a new resource type. The following creates a new resource type
-   `nova_compute` with a required attribute `host_name`:
+   named `nova_compute` with a required attribute `host_name`:
 
 .. code::
 
@@ -81,9 +82,10 @@ The following operations are supported:
 
 .. note::
 
-    Do not modify the existing change steps when making changes. Each modification
+    Do not modify the existing change steps when making changes.
-    requires a new step to be added and for `ceilometer-upgrade`
+    Each modification requires a new step to be added and for
-    to be run to apply the change to Gnocchi.
+    `ceilometer-upgrade` to be run to apply the change to Gnocchi.
 
-With accomplishing sections above, don't forget to add a new resource type or attributes of
+With accomplishing sections above, don't forget to add a new resource type or
-a resource type into the :file:`ceilometer/publisher/data/gnocchi_resources.yaml`.
+attributes of a resource type into
+the :file:`ceilometer/publisher/data/gnocchi_resources.yaml`.

doc/source/contributor/plugins.rst

@@ -133,8 +133,9 @@ In the ``InstanceNotifications`` plugin, it listens to three events:
 * compute.instance.delete.start
 
 Using the ``get_event_type`` method and subsequently the method
-``process_notification`` will be invoked each time such events are happening which
+``process_notification`` will be invoked each time such events are happening
-generates the appropriate sample objects to be sent to the publisher targets.
+which generates the appropriate sample objects to be sent to the publisher
+targets.
 
 Adding new plugins
 ------------------
@@ -167,6 +168,6 @@ Tests
 Any new plugin or agent contribution will only be accepted into the project if
 provided together with unit tests.  Those are defined for the compute agent
 plugins in the directory ``tests/unit/compute`` and for the agent itself in
-``tests/unit/agent``. Unit tests are run in a continuous integration process for
+``tests/unit/agent``. Unit tests are run in a continuous integration process
-each commit made to the project, thus ensuring as best as possible that a given
+for each commit made to the project, thus ensuring as best as possible that
-patch has no side effect to the rest of the project.
+a given patch has no side effect to the rest of the project.

doc/source/releasenotes/folsom.rst

@@ -19,14 +19,14 @@
 Folsom
 ====================
 
-This is the first release (Version 0.1) of Ceilometer. Please take all appropriate
+This is the first release (Version 0.1) of Ceilometer. Please take all
-caution in using it, as it is a technology preview at this time.
+appropriate caution in using it, as it is a technology preview at this time.
 
 Version of OpenStack
-   It is currently tested to work with OpenStack 2012.2 Folsom. Due to its use of
+   It is currently tested to work with OpenStack 2012.2 Folsom. Due to its use
-   openstack-common, and the modification that were made in term of notification
+   of openstack-common, and the modification that were made in term of
-   to many other components (glance, cinder, quantum), it will not easily work
+   notification to many other components (glance, cinder, quantum), it will not
-   with any prior version of OpenStack.
+   easily work with any prior version of OpenStack.
 
 Components
    Currently covered components are: Nova, Nova-network, Glance, Cinder and
@@ -35,27 +35,27 @@ Components
    per component can be found at in :ref:`measurements`.
 
 Nova with libvirt only
-   Most of the Nova meters will only work with libvirt fronted hypervisors at the
+   Most of the Nova meters will only work with libvirt fronted hypervisors at
-   moment, and our test coverage was mostly done on KVM. Contributors are welcome
+   the moment, and our test coverage was mostly done on KVM. Contributors are
-   to implement other virtualization backends' meters.
+   welcome to implement other virtualization backends' meters.
 
 Quantum delete events
    Quantum delete notifications do not include the same metadata as the other
    messages, so we ignore them for now. This isn't ideal, since it may mean we
-   miss charging for some amount of time, but it is better than throwing away the
+   miss charging for some amount of time, but it is better than throwing away
-   existing metadata for a resource when it is deleted.
+   the existing metadata for a resource when it is deleted.
 
 Database backend
    The only tested and complete database backend is currently MongoDB, the
    SQLAlchemy one is still work in progress.
 
 Installation
-   The current best source of information on how to deploy this project is found
+   The current best source of information on how to deploy this project is
-   as the devstack implementation but feel free to come to #openstack-metering on
+   found as the devstack implementation but feel free to come to
-   freenode for more info.
+   #openstack-metering on freenode for more info.
 
 Volume of data
-   Please note that metering can generate lots of data very quickly. Have a look
+   Please note that metering can generate lots of data very quickly. Have a
-   at the following spreadsheet to evaluate what you will end up with.
+   look at the following spreadsheet to evaluate what you will end up with.
 
       https://wiki.openstack.org/wiki/EfficientMetering#Volume_of_data

tox.ini

@@ -37,8 +37,10 @@ commands =
 
 [testenv:pep8]
 deps = hacking<0.13,>=0.12
+       doc8
 commands =
     flake8
+    doc8 {posargs}
     # Check that .po and .pot files are valid:
     bash -c "find ceilometer -type f -regex '.*\.pot?' -print0|xargs -0 -n 1 msgfmt --check-format -o /dev/null"
 
@@ -56,6 +58,10 @@ setenv = PYTHONHASHSEED=0
 commands = {posargs}
 setenv = PYTHONHASHSEED=0
 
+[doc8]
+ignore = D000
+ignore-path = .venv,.git,.tox,*ceilometer/locale*,*lib/python*,ceilometer.egg*,doc/build,doc/source/api,releasenotes/*
+
 [flake8]
 ignore =
 exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build,install-guide