docs: Fix incorrect docstrings in reStructuredText format

Several docstrings have incorrect format, what prevents to generate
a documentation using sphinx-apidoc extension.

Change-Id: I66431c7030089173d7635c1e2a72765db21f9780

HACKING.rst

@@ -6,7 +6,7 @@ Tempest Coding Guide
 - Step 2: Read on
 
 Tempest Specific Commandments
-------------------------------
+-----------------------------
 
 - [T102] Cannot import OpenStack python clients in tempest/api &
   tempest/scenario tests

doc/source/data/tempest-plugins-registry.header

@@ -3,9 +3,9 @@
   job.  You should edit the files data/tempest-plugins-registry.footer
   and data/tempest-plugins-registry.header instead of this one.
 
-==========================
+=======================
- Tempest Plugin Registry
+Tempest Plugin Registry
-==========================
+=======================
 
 Since we've created the external plugin mechanism, it's gotten used by
 a lot of projects. The following is a list of plugins that currently

tempest/api/compute/admin/test_volume_swap.py

@@ -70,6 +70,7 @@ class TestVolumeSwap(TestVolumeSwapBase):
     """The test suite for swapping of volume with admin user.
 
     The following is the scenario outline:
+
     1. Create a volume "volume1" with non-admin.
     2. Create a volume "volume2" with non-admin.
     3. Boot an instance "instance1" with non-admin.

tempest/api/compute/base.py

@@ -477,7 +477,7 @@ class BaseV2ComputeTest(api_version_utils.BaseMicroversionTest,
         """Create a volume and wait for it to become 'available'.
 
         :param image_ref: Specify an image id to create a bootable volume.
-        :**kwargs: other parameters to create volume.
+        :param kwargs: other parameters to create volume.
         :returns: The available volume.
         """
         if 'size' not in kwargs:

tempest/api/object_storage/test_container_quotas.py

@@ -31,9 +31,10 @@ class ContainerQuotasTest(base.BaseObjectTest):
 
         Quotas are set by adding meta values to the container,
         and are validated when set:
-          - X-Container-Meta-Quota-Bytes:
+
+        - X-Container-Meta-Quota-Bytes:
                      Maximum size of the container, in bytes.
-          - X-Container-Meta-Quota-Count:
+        - X-Container-Meta-Quota-Count:
                      Maximum object count of the container.
         """
         super(ContainerQuotasTest, self).setUp()

tempest/common/compute.py

@@ -78,23 +78,22 @@ def create_test_server(clients, validatable=False, validation_resources=None,
     :param wait_until: Server status to wait for the server to reach after
         its creation.
     :param volume_backed: Whether the server is volume backed or not.
-                          If this is true, a volume will be created and
+        If this is true, a volume will be created and create server will be
-                          create server will be requested with
+        requested with 'block_device_mapping_v2' populated with below values:
-                          'block_device_mapping_v2' populated with below
+
-                          values:
+        .. code-block:: python
-                          --------------------------------------------
+
-                          bd_map_v2 = [{
+            bd_map_v2 = [{
-                              'uuid': volume['volume']['id'],
+                'uuid': volume['volume']['id'],
-                              'source_type': 'volume',
+                'source_type': 'volume',
-                              'destination_type': 'volume',
+                'destination_type': 'volume',
-                              'boot_index': 0,
+                'boot_index': 0,
-                              'delete_on_termination': True}]
+                'delete_on_termination': True}]
-                          kwargs['block_device_mapping_v2'] = bd_map_v2
+            kwargs['block_device_mapping_v2'] = bd_map_v2
-                          ---------------------------------------------
+
-                          If server needs to be booted from volume with other
+        If server needs to be booted from volume with other combination of bdm
-                          combination of bdm inputs than mentioned above, then
+        inputs than mentioned above, then pass the bdm inputs explicitly as
-                          pass the bdm inputs explicitly as kwargs and image_id
+        kwargs and image_id as empty string ('').
-                          as empty string ('').
     :param name: Name of the server to be provisioned. If not defined a random
         string ending with '-instance' will be generated.
     :param flavor: Flavor of the server to be provisioned. If not defined,

tempest/common/identity.py

@@ -64,7 +64,8 @@ def identity_utils(clients):
     should not be used for testing identity features.
 
     :param clients: a client manager.
-    :return
+    :return: v2 or v3 of CredsClient
+    :rtype: V2CredsClient or V3CredsClient
     """
     if CONF.identity.auth_version == 'v2':
         client = clients.identity_client

tempest/lib/common/fixed_network.py

@@ -24,7 +24,7 @@ def get_network_from_name(name, compute_networks_client):
     """Get a full network dict from just a network name
 
     :param str name: the name of the network to use
-    :param NetworksClient compute_networks_client: The network client
+    :param network.NetworksClient compute_networks_client: The network client
         object to use for making the network lists api request
     :return: The full dictionary for the network in question
     :rtype: dict

tempest/lib/common/utils/data_utils.py

@@ -65,9 +65,9 @@ def rand_password(length=15):
     :param int length: The length of password that you expect to set
                        (If it's smaller than 3, it's same as 3.)
     :return: a random password. The format is
-             '<random upper letter>-<random number>-<random special character>
+        ``'<random upper letter>-<random number>-<random special character>
-              -<random ascii letters or digit characters or special symbols>'
+        -<random ascii letters or digit characters or special symbols>'``
-             (e.g. 'G2*ac8&lKFFgh%2')
+        (e.g. ``G2*ac8&lKFFgh%2``)
     :rtype: string
     """
     upper = random.choice(string.ascii_uppercase)

tempest/lib/services/volume/v1/types_client.py

@@ -149,10 +149,11 @@ class TypesClient(rest_client.RestClient):
                                        extra_specs):
         """Update a volume_type extra spec.
 
-        volume_type_id: Id of volume_type.
+        :param volume_type_id: Id of volume_type.
-        extra_spec_name: Name of the extra spec to be updated.
+        :param extra_spec_name: Name of the extra spec to be updated.
-        extra_spec: A dictionary of with key as extra_spec_name and the
+        :param extra_specs: A dictionary of with key as extra_spec_name and the
-                     updated value.
+                            updated value.
+
         For a full list of available parameters, please refer to the official
         API reference:
         https://developer.openstack.org/api-ref/block-storage/v2/#update-extra-specs-for-a-volume-type

tempest/lib/services/volume/v3/types_client.py

@@ -153,6 +153,7 @@ class TypesClient(rest_client.RestClient):
         :param extra_spec_name: Name of the extra spec to be updated.
         :param extra_specs: A dictionary of with key as extra_spec_name and the
                             updated value.
+
         For a full list of available parameters, please refer to the official
         API reference:
         https://developer.openstack.org/api-ref/block-storage/v3/index.html#update-extra-specification-for-volume-type

tempest/lib/services/volume/v3/volumes_client.py

@@ -182,7 +182,7 @@ class VolumesClient(base_client.BaseClient):
 
         :param id: A checked resource id
         :raises lib_exc.DeleteErrorException: If the specified resource is on
-        the status the delete was failed.
+            the status the delete was failed.
         """
         try:
             volume = self.show_volume(id)

tempest/scenario/manager.py

@@ -378,12 +378,12 @@ class ScenarioTest(tempest.test.BaseTestCase):
                           server=None):
         """Get a SSH client to a remote server
 
-        @param ip_address the server floating or fixed IP address to use
+        :param ip_address: the server floating or fixed IP address to use
-                          for ssh validation
+                           for ssh validation
-        @param username name of the Linux account on the remote server
+        :param username: name of the Linux account on the remote server
-        @param private_key the SSH private key to use
+        :param private_key: the SSH private key to use
-        @param server: server dict, used for debugging purposes
+        :param server: server dict, used for debugging purposes
-        @return a RemoteClient object
+        :return: a RemoteClient object
         """
 
         if username is None:

tempest/scenario/test_encrypted_cinder_volumes.py

@@ -29,11 +29,12 @@ class TestEncryptedCinderVolumes(manager.EncryptionScenarioTest):
 
     For both LUKS and cryptsetup encryption types, this test performs
     the following:
-        * Creates an image in Glance
+
-        * Boots an instance from the image
+    * Creates an image in Glance
-        * Creates an encryption type (as admin)
+    * Boots an instance from the image
-        * Creates a volume of that encryption type (as a regular user)
+    * Creates an encryption type (as admin)
-        * Attaches and detaches the encrypted volume to the instance
+    * Creates a volume of that encryption type (as a regular user)
+    * Attaches and detaches the encrypted volume to the instance
     """
 
     @classmethod

tempest/scenario/test_network_basic_ops.py

@@ -374,39 +374,37 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
     def test_network_basic_ops(self):
         """Basic network operation test
 
-        For a freshly-booted VM with an IP address ("port") on a given
+        For a freshly-booted VM with an IP address ("port") on a given network:
-            network:
 
         - the Tempest host can ping the IP address.  This implies, but
-         does not guarantee (see the ssh check that follows), that the
+            does not guarantee (see the ssh check that follows), that the
-         VM has been assigned the correct IP address and has
+            VM has been assigned the correct IP address and has
-         connectivity to the Tempest host.
+            connectivity to the Tempest host.
 
         - the Tempest host can perform key-based authentication to an
-         ssh server hosted at the IP address.  This check guarantees
+            ssh server hosted at the IP address.  This check guarantees
-         that the IP address is associated with the target VM.
+            that the IP address is associated with the target VM.
 
         - the Tempest host can ssh into the VM via the IP address and
-         successfully execute the following:
+            successfully execute the following:
 
-         - ping an external IP address, implying external connectivity.
+            - ping an external IP address, implying external connectivity.
 
-         - ping an external hostname, implying that dns is correctly
+            - ping an external hostname, implying that dns is correctly
-           configured.
+                configured.
 
-         - ping an internal IP address, implying connectivity to another
+            - ping an internal IP address, implying connectivity to another
-           VM on the same network.
+               VM on the same network.
 
         - detach the floating-ip from the VM and verify that it becomes
-        unreachable
+            unreachable
 
         - associate detached floating ip to a new VM and verify connectivity.
-        VMs are created with unique keypair so connectivity also asserts that
+            VMs are created with unique keypair so connectivity also asserts
-        floating IP is associated with the new VM instead of the old one
+            that floating IP is associated with the new VM instead of the old
+            one
 
         Verifies that floating IP status is updated correctly after each change
-
-
         """
         self._setup_network_and_servers()
         self._check_public_network_connectivity(should_connect=True)
@@ -445,30 +443,25 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
     def test_connectivity_between_vms_on_different_networks(self):
         """Test connectivity between VMs on different networks
 
-        For a freshly-booted VM with an IP address ("port") on a given
+        For a freshly-booted VM with an IP address ("port") on a given network:
-            network:
 
         - the Tempest host can ping the IP address.
-
         - the Tempest host can ssh into the VM via the IP address and
-         successfully execute the following:
+            successfully execute the following:
 
-         - ping an external IP address, implying external connectivity.
+            - ping an external IP address, implying external connectivity.
-
+            - ping an external hostname, implying that dns is correctly
-         - ping an external hostname, implying that dns is correctly
+               configured.
-           configured.
+            - ping an internal IP address, implying connectivity to another
-
+               VM on the same network.
-         - ping an internal IP address, implying connectivity to another
-           VM on the same network.
 
         - Create another network on the same tenant with subnet, create
-        an VM on the new network.
+            an VM on the new network.
 
-         - Ping the new VM from previous VM failed since the new network
+            - Ping the new VM from previous VM failed since the new network
-         was not attached to router yet.
+                was not attached to router yet.
-
+            - Attach the new network to the router, Ping the new VM from
-         - Attach the new network to the router, Ping the new VM from
+                previous VM succeed.
-         previous VM succeed.
 
         """
         self._setup_network_and_servers()
@@ -561,24 +554,25 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
     def test_subnet_details(self):
         """Tests that subnet's extra configuration details are affecting VMs.
 
-         This test relies on non-shared, isolated tenant networks.
+        This test relies on non-shared, isolated tenant networks.
 
-         NOTE: Neutron subnets push data to servers via dhcp-agent, so any
+        NOTE: Neutron subnets push data to servers via dhcp-agent, so any
-         update in subnet requires server to actively renew its DHCP lease.
+        update in subnet requires server to actively renew its DHCP lease.
 
-         1. Configure subnet with dns nameserver
+        1. Configure subnet with dns nameserver
-         2. retrieve the VM's configured dns and verify it matches the one
+        2. retrieve the VM's configured dns and verify it matches the one
-         configured for the subnet.
+           configured for the subnet.
-         3. update subnet's dns
+        3. update subnet's dns
-         4. retrieve the VM's configured dns and verify it matches the new one
+        4. retrieve the VM's configured dns and verify it matches the new one
-         configured for the subnet.
+           configured for the subnet.
 
-         TODO(yfried): add host_routes
+        TODO(yfried): add host_routes
 
-         any resolution check would be testing either:
+        any resolution check would be testing either:
-            * l3 forwarding (tested in test_network_basic_ops)
+
-            * Name resolution of an external DNS nameserver - out of scope for
+        * l3 forwarding (tested in test_network_basic_ops)
-            Tempest
+        * Name resolution of an external DNS nameserver - out of scope for
+          Tempest
         """
         # this test check only updates (no actual resolution) so using
         # arbitrary ip addresses as nameservers, instead of parsing CONF
@@ -748,7 +742,7 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
         2. Remove router from all l3-agents
         3. Verify connectivity is down
         4. Assign router to new l3-agent (or old one if no new agent is
-         available)
+           available)
         5. Verify connectivity
         """
 
@@ -829,7 +823,8 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
         prevents traffic to pass through the VM. Anti-spoof rules are not
         required in cases where the VM routes traffic through it.
 
-        The test steps are :
+        The test steps are:
+
         1. Create a new network.
         2. Connect (hotplug) the VM to a new network.
         3. Check the VM can ping a server on the new network ("peer")
@@ -838,7 +833,7 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
            spoofed interface (VM cannot ping the peer).
         6. Disable port-security of the spoofed port- set the flag to false.
         7. Retest 3rd step and check that the Security Group allows pings via
-        the spoofed interface.
+           the spoofed interface.
         """
 
         spoof_mac = "00:00:00:00:00:01"

tempest/scenario/test_object_storage_basic_ops.py

@@ -24,15 +24,15 @@ class TestObjectStorageBasicOps(manager.ObjectStorageScenarioTest):
     def test_swift_basic_ops(self):
         """Test swift basic ops.
 
-         * get swift stat.
+        * get swift stat.
-         * create container.
+        * create container.
-         * upload a file to the created container.
+        * upload a file to the created container.
-         * list container's objects and assure that the uploaded file is
+        * list container's objects and assure that the uploaded file is
-         present.
+          present.
-         * download the object and check the content
+        * download the object and check the content
-         * delete object from container.
+        * delete object from container.
-         * list container's objects and assure that the deleted file is gone.
+        * list container's objects and assure that the deleted file is gone.
-         * delete a container.
+        * delete a container.
         """
         self.get_swift_stat()
         container_name = self.create_container()

tempest/scenario/test_security_groups_basic_ops.py

@@ -63,28 +63,28 @@ class TestSecurityGroupsBasicOps(manager.NetworkScenarioTest):
                 a. a security group open to incoming ssh connection
                 b. a VM with a floating ip
             5. create a general empty security group (same as "default", but
-            without rules allowing in-tenant traffic)
+               without rules allowing in-tenant traffic)
 
     tests:
         1. _verify_network_details
         2. _verify_mac_addr: for each access point verify that
-        (subnet, fix_ip, mac address) are as defined in the port list
+           (subnet, fix_ip, mac address) are as defined in the port list
         3. _test_in_tenant_block: test that in-tenant traffic is disabled
-        without rules allowing it
+           without rules allowing it
         4. _test_in_tenant_allow: test that in-tenant traffic is enabled
-        once an appropriate rule has been created
+           once an appropriate rule has been created
         5. _test_cross_tenant_block: test that cross-tenant traffic is disabled
-        without a rule allowing it on destination tenant
+           without a rule allowing it on destination tenant
         6. _test_cross_tenant_allow:
             * test that cross-tenant traffic is enabled once an appropriate
-            rule has been created on destination tenant.
+              rule has been created on destination tenant.
             * test that reverse traffic is still blocked
             * test than reverse traffic is enabled once an appropriate rule has
-            been created on source tenant
+              been created on source tenant
-        7._test_port_update_new_security_group:
+        7. _test_port_update_new_security_group:
-           * test that traffic is blocked with default security group
+            * test that traffic is blocked with default security group
-           * test that traffic is enabled after updating port with new security
+            * test that traffic is enabled after updating port with new
-           group having appropriate rule
+              security group having appropriate rule
         8. _test_multiple_security_groups: test multiple security groups can be
            associated with the vm
 
@@ -93,11 +93,13 @@ class TestSecurityGroupsBasicOps(manager.NetworkScenarioTest):
         2. Public network is defined and reachable from the Tempest host
         3. Public router can either be:
             * defined, in which case all tenants networks can connect directly
-            to it, and cross tenant check will be done on the private IP of the
+              to it, and cross tenant check will be done on the private IP of
-            destination tenant
+              the destination tenant
+
             or
+
             * not defined (empty string), in which case each tenant will have
-            its own router connected to the public network
+              its own router connected to the public network
     """
 
     credentials = ['primary', 'alt', 'admin']

tempest/test.py

@@ -259,6 +259,7 @@ class BaseTestCase(testtools.testcase.WithAttributes,
         based on the result of an API call are discouraged.
 
         The following checks are implemented in `test.py` already:
+
         - check that alt credentials are available when requested by the test
         - check that admin credentials are available when requested by the test
         - check that the identity version specified by the test is marked as
@@ -310,6 +311,7 @@ class BaseTestCase(testtools.testcase.WithAttributes,
         `os_[type]`:
 
         Valid values in `credentials` are:
+
         - 'primary':
             A normal user is provisioned.
             It can be used only once. Multiple entries will be ignored.