Add doc8 rule and check doc/source files

doc8 is a linter for documents and used in openstack-manuals.
It is better to enforce document linters for simple checking.
This change is to add doc8 in tox file and fix line too long
in some files.

The current rules are as bellow:
- invalid rst format - D000
- lines should not be longer than 79 characters - D001
  - RST exception: line with no whitespace except in the beginning
  - RST exception: lines with http or https urls
  - RST exception: literal blocks
  - RST exception: rst target directives
- no trailing whitespace - D002
- no tabulation for indentation - D003
- no carriage returns (use unix newlines) - D004
- no newline at end of file - D005

Change-Id: I5b409fbfd95e05921310c6ecf4afea0220fb0bf0

doc/source/contributors/index.rst

@@ -50,9 +50,9 @@ Testing
 
 The project contains three test packages, one for unit tests, one for
 functional tests and one for examples tests. The ``openstack.tests.unit``
-package tests the SDK's features in isolation. The ``openstack.tests.functional``
+package tests the SDK's features in isolation. The
-and ``openstack.tests.examples`` packages test the SDK's features and examples
+``openstack.tests.functional`` and ``openstack.tests.examples`` packages test
-against an OpenStack cloud.
+the SDK's features and examples against an OpenStack cloud.
 
 .. toctree::
 

doc/source/contributors/testing.rst

@@ -76,7 +76,8 @@ under ``clouds`` must be named ``test_cloud``.
 .. literalinclude:: clouds.yaml
    :language: yaml
 
-Replace ``xxx.xxx.xxx.xxx`` with the IP address or FQDN of your DevStack instance.
+Replace ``xxx.xxx.xxx.xxx`` with the IP address or FQDN of your DevStack
+instance.
 
 You can also create a ``~/.config/openstack/clouds.yaml`` file for your
 DevStack cloud environment using the following commands. Replace
@@ -114,8 +115,8 @@ practice, this means that the tests should initially be run against a stable
 branch of `DevStack <https://docs.openstack.org/devstack/latest/>`_.
 And like the functional tests, the examples tests connect to an OpenStack cloud
 using `os-client-config <http://git.openstack.org/cgit/openstack/os-client-config/tree/README.rst>`_.
-See the functional tests instructions for information on setting up DevStack and
+See the functional tests instructions for information on setting up DevStack
-os-client-config.
+and os-client-config.
 
 Run
 ***

doc/source/users/guides/compute.rst

@@ -86,4 +86,4 @@ Full example: `compute resource create`_
 .. _compute resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/compute/list.py
 .. _network resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/list.py
 .. _compute resource create: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/compute/create.py
-.. _public–key cryptography: https://en.wikipedia.org/wiki/Public-key_cryptography
+.. _public–key cryptography: https://en.wikipedia.org/wiki/Public-key_cryptography

doc/source/users/guides/logging.rst

@@ -26,7 +26,8 @@ To log debug and higher messages::
     utils.enable_logging(debug=True, stream=sys.stdout)
 
 The ``path`` parameter controls the location of a log file. If set, this
-parameter will send log messages to a file using a :py:class:`~logging.FileHandler`.
+parameter will send log messages to a file using a
+:py:class:`~logging.FileHandler`.
 
 To log messages to a file called ``openstack.log``::
 

doc/source/users/guides/network.rst

@@ -14,11 +14,12 @@ List Networks
 -------------
 
 A **network** is an isolated `Layer 2 <https://en.wikipedia.org/wiki/Data_link_layer>`_
-networking segment. There are two types of networks, project and provider networks.
+networking segment. There are two types of networks, project and provider
-Project networks are fully isolated and are not shared with other projects. Provider
+networks. Project networks are fully isolated and are not shared with other
-networks map to existing physical networks in the data center and provide external
+projects. Provider networks map to existing physical networks in the data
-network access for servers. Only an OpenStack administrator can create provider
+center and provide external network access for servers. Only an OpenStack
-networks. Networks can be connected via routers.
+administrator can create provider networks. Networks can be connected via
+routers.
 
 .. literalinclude:: ../examples/network/list.py
    :pyobject: list_networks
@@ -66,10 +67,11 @@ Full example: `network resource list`_
 List Routers
 ------------
 
-A **router** is a logical component that forwards data packets between networks.
+A **router** is a logical component that forwards data packets between
-It also provides `Layer 3 <https://en.wikipedia.org/wiki/Network_layer>`_ and
+networks. It also provides
-`NAT <https://en.wikipedia.org/wiki/Network_address_translation>`_ forwarding to
+`Layer 3 <https://en.wikipedia.org/wiki/Network_layer>`_ and
-provide external network access for servers on project networks.
+`NAT <https://en.wikipedia.org/wiki/Network_address_translation>`_
+forwarding to provide external network access for servers on project networks.
 
 .. literalinclude:: ../examples/network/list.py
    :pyobject: list_routers

doc/source/users/resources/compute/v2/limits.rst

@@ -14,7 +14,8 @@ The ``Limits`` class inherits from :class:`~openstack.resource.Resource`.
 The AbsoluteLimits Class
 ------------------------
 
-The ``AbsoluteLimits`` class inherits from :class:`~openstack.resource.Resource`.
+The ``AbsoluteLimits`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.compute.v2.limits.AbsoluteLimits
    :members:

doc/source/users/resources/compute/v2/server_interface.rst

@@ -6,7 +6,8 @@ openstack.compute.v2.server_interface
 The ServerInterface Class
 -------------------------
 
-The ``ServerInterface`` class inherits from :class:`~openstack.resource.Resource`.
+The ``ServerInterface`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.compute.v2.server_interface.ServerInterface
    :members:

doc/source/users/resources/load_balancer/v2/health_monitor.rst

@@ -6,7 +6,8 @@ openstack.load_balancer.v2.health_monitor
 The HealthMonitor Class
 -----------------------
 
-The ``HealthMonitor`` class inherits from :class:`~openstack.resource.Resource`.
+The ``HealthMonitor`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.load_balancer.v2.health_monitor.HealthMonitor
    :members:

doc/source/users/resources/metric/v1/archive_policy.rst

@@ -6,7 +6,8 @@ openstack.metric.v1.archive_policy
 The ArchivePolicy Class
 -----------------------
 
-The ``ArchivePolicy`` class inherits from :class:`~openstack.resource.Resource`.
+The ``ArchivePolicy`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.metric.v1.archive_policy.ArchivePolicy
    :members:

doc/source/users/resources/network/v2/auto_allocated_topology.rst

@@ -6,7 +6,8 @@ openstack.network.v2.auto_allocated_topology
 The Auto Allocated Topology Class
 ---------------------------------
 
-The ``Auto Allocated Toplogy`` class inherits from :class:`~openstack.resource.Resource`.
+The ``Auto Allocated Toplogy`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.auto_allocated_topology.AutoAllocatedTopology
    :members:

doc/source/users/resources/network/v2/availability_zone.rst

@@ -6,7 +6,8 @@ openstack.network.v2.availability_zone
 The AvailabilityZone Class
 --------------------------
 
-The ``AvailabilityZone`` class inherits from :class:`~openstack.resource.Resource`.
+The ``AvailabilityZone`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.availability_zone.AvailabilityZone
    :members:

doc/source/users/resources/network/v2/health_monitor.rst

@@ -6,7 +6,8 @@ openstack.network.v2.health_monitor
 The HealthMonitor Class
 -----------------------
 
-The ``HealthMonitor`` class inherits from :class:`~openstack.resource.Resource`.
+The ``HealthMonitor`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.health_monitor.HealthMonitor
    :members:

doc/source/users/resources/network/v2/metering_label.rst

@@ -6,7 +6,8 @@ openstack.network.v2.metering_label
 The MeteringLabel Class
 -----------------------
 
-The ``MeteringLabel`` class inherits from :class:`~openstack.resource.Resource`.
+The ``MeteringLabel`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.metering_label.MeteringLabel
    :members:

doc/source/users/resources/network/v2/metering_label_rule.rst

@@ -6,7 +6,8 @@ openstack.network.v2.metering_label_rule
 The MeteringLabelRule Class
 ---------------------------
 
-The ``MeteringLabelRule`` class inherits from :class:`~openstack.resource.Resource`.
+The ``MeteringLabelRule`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.metering_label_rule.MeteringLabelRule
    :members:

doc/source/users/resources/network/v2/network_ip_availability.rst

@@ -6,7 +6,8 @@ openstack.network.v2.network_ip_availability
 The NetworkIPAvailability Class
 -------------------------------
 
-The ``NetworkIPAvailability`` class inherits from :class:`~openstack.resource.Resource`.
+The ``NetworkIPAvailability`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.network_ip_availability.NetworkIPAvailability
    :members:

doc/source/users/resources/network/v2/qos_bandwidth_limit_rule.rst

@@ -6,7 +6,8 @@ openstack.network.v2.qos_bandwidth_limit_rule
 The QoSBandwidthLimitRule Class
 -------------------------------
 
-The ``QoSBandwidthLimitRule`` class inherits from :class:`~openstack.resource.Resource`.
+The ``QoSBandwidthLimitRule`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.qos_bandwidth_limit_rule.QoSBandwidthLimitRule
    :members:

doc/source/users/resources/network/v2/qos_dscp_marking_rule.rst

@@ -6,7 +6,8 @@ openstack.network.v2.qos_dscp_marking_rule
 The QoSDSCPMarkingRule Class
 ----------------------------
 
-The ``QoSDSCPMarkingRule`` class inherits from :class:`~openstack.resource.Resource`.
+The ``QoSDSCPMarkingRule`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.qos_dscp_marking_rule.QoSDSCPMarkingRule
    :members:

doc/source/users/resources/network/v2/qos_minimum_bandwidth_rule.rst

@@ -6,7 +6,8 @@ openstack.network.v2.qos_minimum_bandwidth_rule
 The QoSMinimumBandwidthRule Class
 ---------------------------------
 
-The ``QoSMinimumBandwidthRule`` class inherits from :class:`~openstack.resource.Resource`.
+The ``QoSMinimumBandwidthRule`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.qos_minimum_bandwidth_rule.QoSMinimumBandwidthRule
    :members:

doc/source/users/resources/network/v2/rbac_policy.rst

@@ -9,4 +9,4 @@ The RBACPolicy Class
 The ``RBACPolicy`` class inherits from :class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.rbac_policy.RBACPolicy
-   :members:
+   :members:

doc/source/users/resources/network/v2/security_group.rst

@@ -6,7 +6,8 @@ openstack.network.v2.security_group
 The SecurityGroup Class
 -----------------------
 
-The ``SecurityGroup`` class inherits from :class:`~openstack.resource.Resource`.
+The ``SecurityGroup`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.security_group.SecurityGroup
    :members:

doc/source/users/resources/network/v2/security_group_rule.rst

@@ -6,7 +6,8 @@ openstack.network.v2.security_group_rule
 The SecurityGroupRule Class
 ---------------------------
 
-The ``SecurityGroupRule`` class inherits from :class:`~openstack.resource.Resource`.
+The ``SecurityGroupRule`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.security_group_rule.SecurityGroupRule
    :members:

doc/source/users/resources/network/v2/service_profile.rst

@@ -6,7 +6,8 @@ openstack.network.v2.service_profile
 The ServiceProfile Class
 ------------------------
 
-The ``ServiceProfile`` class inherits from :class:`~openstack.resource.Resource`.
+The ``ServiceProfile`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.service_profile.ServiceProfile
    :members:

doc/source/users/resources/network/v2/service_provider.rst

@@ -6,7 +6,8 @@ openstack.network.v2.service_provider
 The Service Provider Class
 --------------------------
 
-The ``Service Provider`` class inherits from :class:`~openstack.resource.Resource`.
+The ``Service Provider`` class inherits from
+:class:`~openstack.resource.Resource`.
 
 .. autoclass:: openstack.network.v2.service_provider.ServiceProvider
    :members:

test-requirements.txt

@@ -5,6 +5,7 @@ hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
 
 beautifulsoup4>=4.6.0 # MIT
 coverage!=4.4,>=4.0 # Apache-2.0
+doc8 # Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD
 mock>=2.0.0 # BSD
 python-subunit>=0.0.18 # Apache-2.0/BSD

tox.ini

@@ -41,9 +41,16 @@ commands = {posargs}
 commands = python setup.py test --coverage --coverage-package-name=openstack --testr-args='{posargs}'
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = 
+  doc8 doc/source
+  python setup.py build_sphinx
 
 [flake8]
 ignore=D100,D101,D102,D103,D104,D105,D200,D202,D204,D205,D211,D301,D400,D401
 show-source = True
 exclude=.venv,.git,.tox,dist,doc,*lib/python*,*egg,build
+
+[doc8]
+extensions = .rst, .yaml
+# Maximal line length should be 80.
+max-line-length = 80