From f18dc29eb09da2b26922022b4284edfb95e5217c Mon Sep 17 00:00:00 2001 From: liuxiaoyang Date: Wed, 23 Aug 2017 09:31:43 +0800 Subject: [PATCH] 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 | 6 +++--- doc/source/contributors/testing.rst | 7 ++++--- doc/source/users/guides/compute.rst | 2 +- doc/source/users/guides/logging.rst | 3 ++- doc/source/users/guides/network.rst | 20 ++++++++++--------- .../users/resources/compute/v2/limits.rst | 3 ++- .../resources/compute/v2/server_interface.rst | 3 ++- .../load_balancer/v2/health_monitor.rst | 3 ++- .../resources/metric/v1/archive_policy.rst | 3 ++- .../network/v2/auto_allocated_topology.rst | 3 ++- .../network/v2/availability_zone.rst | 3 ++- .../resources/network/v2/health_monitor.rst | 3 ++- .../resources/network/v2/metering_label.rst | 3 ++- .../network/v2/metering_label_rule.rst | 3 ++- .../network/v2/network_ip_availability.rst | 3 ++- .../network/v2/qos_bandwidth_limit_rule.rst | 3 ++- .../network/v2/qos_dscp_marking_rule.rst | 3 ++- .../network/v2/qos_minimum_bandwidth_rule.rst | 3 ++- .../resources/network/v2/rbac_policy.rst | 2 +- .../resources/network/v2/security_group.rst | 3 ++- .../network/v2/security_group_rule.rst | 3 ++- .../resources/network/v2/service_profile.rst | 3 ++- .../resources/network/v2/service_provider.rst | 3 ++- test-requirements.txt | 1 + tox.ini | 9 ++++++++- 25 files changed, 65 insertions(+), 36 deletions(-) diff --git a/doc/source/contributors/index.rst b/doc/source/contributors/index.rst index 8b246a245..67c5b261f 100644 --- a/doc/source/contributors/index.rst +++ b/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`` -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:: diff --git a/doc/source/contributors/testing.rst b/doc/source/contributors/testing.rst index 32d7419e4..0998abe24 100644 --- a/doc/source/contributors/testing.rst +++ b/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 `_. And like the functional tests, the examples tests connect to an OpenStack cloud using `os-client-config `_. -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 *** diff --git a/doc/source/users/guides/compute.rst b/doc/source/users/guides/compute.rst index cc06fa28c..3954d584b 100644 --- a/doc/source/users/guides/compute.rst +++ b/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 \ No newline at end of file +.. _public–key cryptography: https://en.wikipedia.org/wiki/Public-key_cryptography diff --git a/doc/source/users/guides/logging.rst b/doc/source/users/guides/logging.rst index 623916fad..00014e6b7 100644 --- a/doc/source/users/guides/logging.rst +++ b/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``:: diff --git a/doc/source/users/guides/network.rst b/doc/source/users/guides/network.rst index ae9a28b69..b403c4a6e 100644 --- a/doc/source/users/guides/network.rst +++ b/doc/source/users/guides/network.rst @@ -14,11 +14,12 @@ List Networks ------------- A **network** is an isolated `Layer 2 `_ -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 `_ and -`NAT `_ 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 `_ and +`NAT `_ +forwarding to provide external network access for servers on project networks. .. literalinclude:: ../examples/network/list.py :pyobject: list_routers diff --git a/doc/source/users/resources/compute/v2/limits.rst b/doc/source/users/resources/compute/v2/limits.rst index 090988bb9..f30ff2ffc 100644 --- a/doc/source/users/resources/compute/v2/limits.rst +++ b/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: diff --git a/doc/source/users/resources/compute/v2/server_interface.rst b/doc/source/users/resources/compute/v2/server_interface.rst index e67d9964a..922606fb4 100644 --- a/doc/source/users/resources/compute/v2/server_interface.rst +++ b/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: diff --git a/doc/source/users/resources/load_balancer/v2/health_monitor.rst b/doc/source/users/resources/load_balancer/v2/health_monitor.rst index c5143e0df..7f90f4261 100644 --- a/doc/source/users/resources/load_balancer/v2/health_monitor.rst +++ b/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: diff --git a/doc/source/users/resources/metric/v1/archive_policy.rst b/doc/source/users/resources/metric/v1/archive_policy.rst index 903aaa4f0..7358e795e 100644 --- a/doc/source/users/resources/metric/v1/archive_policy.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/auto_allocated_topology.rst b/doc/source/users/resources/network/v2/auto_allocated_topology.rst index f27241c50..a3700d087 100644 --- a/doc/source/users/resources/network/v2/auto_allocated_topology.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/availability_zone.rst b/doc/source/users/resources/network/v2/availability_zone.rst index a33f2b65e..da386ce6d 100644 --- a/doc/source/users/resources/network/v2/availability_zone.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/health_monitor.rst b/doc/source/users/resources/network/v2/health_monitor.rst index 63a029cd1..76cf6a7e8 100644 --- a/doc/source/users/resources/network/v2/health_monitor.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/metering_label.rst b/doc/source/users/resources/network/v2/metering_label.rst index dacb3801b..d07f02512 100644 --- a/doc/source/users/resources/network/v2/metering_label.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/metering_label_rule.rst b/doc/source/users/resources/network/v2/metering_label_rule.rst index 390884933..9bcf7840c 100644 --- a/doc/source/users/resources/network/v2/metering_label_rule.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/network_ip_availability.rst b/doc/source/users/resources/network/v2/network_ip_availability.rst index 3cbbd9f27..900f2461b 100644 --- a/doc/source/users/resources/network/v2/network_ip_availability.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/qos_bandwidth_limit_rule.rst b/doc/source/users/resources/network/v2/qos_bandwidth_limit_rule.rst index 115a55de5..98d904027 100644 --- a/doc/source/users/resources/network/v2/qos_bandwidth_limit_rule.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/qos_dscp_marking_rule.rst b/doc/source/users/resources/network/v2/qos_dscp_marking_rule.rst index 6d2cf9a45..c00023642 100644 --- a/doc/source/users/resources/network/v2/qos_dscp_marking_rule.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/qos_minimum_bandwidth_rule.rst b/doc/source/users/resources/network/v2/qos_minimum_bandwidth_rule.rst index 6ba004b4d..05c52768b 100644 --- a/doc/source/users/resources/network/v2/qos_minimum_bandwidth_rule.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/rbac_policy.rst b/doc/source/users/resources/network/v2/rbac_policy.rst index daf76007a..062da1d7a 100644 --- a/doc/source/users/resources/network/v2/rbac_policy.rst +++ b/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: \ No newline at end of file + :members: diff --git a/doc/source/users/resources/network/v2/security_group.rst b/doc/source/users/resources/network/v2/security_group.rst index 5d4788436..2d0c860a9 100644 --- a/doc/source/users/resources/network/v2/security_group.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/security_group_rule.rst b/doc/source/users/resources/network/v2/security_group_rule.rst index 245720053..8af566ebc 100644 --- a/doc/source/users/resources/network/v2/security_group_rule.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/service_profile.rst b/doc/source/users/resources/network/v2/service_profile.rst index c1c013028..5d66c4473 100644 --- a/doc/source/users/resources/network/v2/service_profile.rst +++ b/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: diff --git a/doc/source/users/resources/network/v2/service_provider.rst b/doc/source/users/resources/network/v2/service_provider.rst index e9d667848..02f912dec 100644 --- a/doc/source/users/resources/network/v2/service_provider.rst +++ b/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: diff --git a/test-requirements.txt b/test-requirements.txt index c82640c82..cb5107be4 100644 --- a/test-requirements.txt +++ b/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 diff --git a/tox.ini b/tox.ini index 789758b43..ac1e695a9 100644 --- a/tox.ini +++ b/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