[ci] Turn on validation of plugins docstings

Change-Id: Iab31e047a1e8e7ac7505413db4cd5776d96061b4

rally_openstack/environment/platforms/existing.py

@@ -263,55 +263,44 @@ class OpenStack(platform.Platform):
     def create_spec_from_sys_environ(cls, sys_environ):
         """Create a spec based on system environment.
 
-        .. envvar:: OS_AUTH_URL
+        * OS_AUTH_URL - The auth url for OpenStack cluster. Supported both
-            The auth url for OpenStack cluster. Supported both versioned and
+          versioned and unversioned urls.
-            unversioned urls.
 
-        .. envvar:: OS_USERNAME
+        * OS_USERNAME - A user name with admin role to use.
-            A user name with admin role to use.
 
-        .. envvar:: OS_PASSWORD
+        * OS_PASSWORD - A password for selected user.
-            A password for selected user.
 
-        .. envvar:: OS_PROJECT_NAME
+        * OS_PROJECT_NAME - Project name to scope to
-            Project name to scope to
 
-        .. envvar:: OS_TENANT_NAME
+        * OS_TENANT_NAME - Project name to scope to (an alternative for
-            Project name to scope to (an alternative for $OS_PROJECT_NAME)
+          $OS_PROJECT_NAME)
 
-        .. envvar:: OS_USER_DOMAIN_NAME
+        * OS_USER_DOMAIN_NAME - User domain name (in case of Keystone V3)
-            User domain name (in case of Keystone V3)
 
-        .. envvar:: OS_PROJECT_DOMAIN_NAME
+        * OS_PROJECT_DOMAIN_NAME - Domain name containing project (in case of
-            Domain name containing project (in case of Keystone V3)
+          Keystone V3)
 
-        .. envvar:: OS_ENDPOINT_TYPE
+        * OS_ENDPOINT_TYPE - Type of endpoint. Valid endpoint types: admin,
-             Type of endpoint. Valid endpoint types: admin, public, internal
+          public, internal
 
-        .. envvar:: OS_INTERFACE
+        * OS_INTERFACE - Type of endpoint (an alternative for OS_ENDPOINT_TYPE)
-             Type of endpoint (an alternative for $OS_INTERFACE)
 
-        .. envvar:: OS_REGION_NAME
+        * OS_REGION_NAME - Authentication region name
-             Authentication region name
 
-        .. envvar:: OS_CACERT
+        * OS_CACERT - A path to CA certificate bundle file
-             A path to CA certificate bundle file
 
-        .. envvar:: OS_CERT
+        * OS_CERT - A path to Client certificate bundle file
-             A path to Client certificate bundle file
 
-        .. envvar:: OS_KEY
+        * OS_KEY - A path to Client certificate key file
-             A path to Client certificate key file
 
-        .. envvar:: OS_INSECURE
+        * OS_INSECURE - Disable server certificate verification
-             Disable server certificate verification
 
-        .. envvar:: OSPROFILER_HMAC_KEY
+        * OSPROFILER_HMAC_KEY - HMAC key to use for encrypting context while
-             HMAC key to use for encrypting context while using osprofiler
+          using osprofiler
+
+        * OSPROFILER_CONN_STR - A connection string for OSProfiler collector
+          to grep profiling results while building html task reports
 
-        .. envvar:: OSPROFILER_CONN_STR
-             A connection string for OSProfiler collector to grep profiling
-             results while building html task reports
         """
 
         from oslo_utils import strutils
@@ -383,9 +372,12 @@ class OpenStack(platform.Platform):
     @classmethod
     def _get_doc(cls):
         doc = cls.__doc__.strip()
-        doc += "\n **Create a spec based on system environment.**\n"
+
-        # cut the first line since we already included the first line of it.
+        env_vars_docs = cls.create_spec_from_sys_environ.__doc__
-        doc += "\n".join(
+        env_vars_description = "\n".join(
-            [line.strip() for line in
+            line for line in env_vars_docs.split("\n")[1:]
-             cls.create_spec_from_sys_environ.__doc__.split("\n")][1:])
+        )
+        doc += (f"\n **The following environment variables are expected for "
+                f"creation a Rally environment using sustem environment "
+                f"variables**\n{env_vars_description}")
         return doc

rally_openstack/task/scenarios/neutron/network.py

@@ -648,6 +648,7 @@ class AssociateAndDissociateFloatingIps(utils.NeutronScenario):
         "openstack floating ip unset" commands performance.
         Because of the prerequisites for "floating ip set/unset" we also
         measure the performance of the following commands:
+
           * "openstack network create"
           * "openstack subnet create"
           * "openstack port create"

rally_openstack/task/scenarios/vm/vmtasks.py

@@ -566,14 +566,17 @@ class CheckDesignateDNSResolving(vm_utils.VMScenario):
         """Try to resolve hostname from VM against existing designate DNS.
 
         - requires zone context with set_zone_in_network parameter
-            zones:
+
-                set_zone_in_network: True
+            > zones:
+            >  set_zone_in_network: True
+
         - designate IP should be in default dns_nameservers list for new
-        networks or it can be specified in a network context
+          networks or it can be specified in a network context
-            network:
+
-                dns_nameservers:
+            > network:
-                   - 8.8.8.8
+            >     dns_nameservers:
-                   - 192.168.210.45
+            >       - 8.8.8.8
+            >       - 192.168.210.45
 
         :param image: glance image name to use for the vm
         :param flavor: VM flavor name

test-requirements.txt

@@ -16,4 +16,6 @@ coverage!=4.4                                          # Apache License, Version
 ddt!=1.4.0                                             # MIT
 testtools                                              # MIT
 
-docutils
+# docs
+docutils
+Pygments

tests/unit/doc/test_docstrings.py

@@ -65,8 +65,6 @@ class DocstringsTestCase(test.TestCase):
     _HAS_VALID_DEFINITIONS = []
 
     def _validate_rst(self, plugin_name, text, msg_buffer):
-        # need to wait till the next release of rally
-        return
         parsed_docstring = _parse_rst(text)
         for item in parsed_docstring:
             if (isinstance(item, nodes.definition_list)