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
This commit is contained in:
liuxiaoyang 2017-08-23 09:31:43 +08:00 committed by Brian Curtin
parent 0eecb4ba71
commit f18dc29eb0
25 changed files with 65 additions and 36 deletions

View File

@ -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``
and ``openstack.tests.examples`` packages test the SDK's features and examples
against an OpenStack cloud.
package tests the SDK's features in isolation. The
``openstack.tests.functional`` and ``openstack.tests.examples`` packages test
the SDK's features and examples against an OpenStack cloud.
.. toctree::

View File

@ -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
os-client-config.
See the functional tests instructions for information on setting up DevStack
and os-client-config.
Run
***

View File

@ -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
.. _publickey cryptography: https://en.wikipedia.org/wiki/Public-key_cryptography
.. _publickey cryptography: https://en.wikipedia.org/wiki/Public-key_cryptography

View File

@ -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``::

View File

@ -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.
Project networks are fully isolated and are not shared with other projects. Provider
networks map to existing physical networks in the data center and provide external
network access for servers. Only an OpenStack administrator can create provider
networks. Networks can be connected via routers.
networking segment. There are two types of networks, project and provider
networks. Project networks are fully isolated and are not shared with other
projects. Provider networks map to existing physical networks in the data
center and provide external network access for servers. Only an OpenStack
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.
It also provides `Layer 3 <https://en.wikipedia.org/wiki/Network_layer>`_ and
`NAT <https://en.wikipedia.org/wiki/Network_address_translation>`_ forwarding to
provide external network access for servers on project networks.
A **router** is a logical component that forwards data packets between
networks. It also provides
`Layer 3 <https://en.wikipedia.org/wiki/Network_layer>`_ and
`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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -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

View File

@ -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