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
-==========================
+=======================
 
 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,6 +31,7 @@ class ContainerQuotasTest(base.BaseObjectTest):
 
         Quotas are set by adding meta values to the container,
         and are validated when set:
+
         - X-Container-Meta-Quota-Bytes:
                      Maximum size of the container, in bytes.
         - X-Container-Meta-Quota-Count:

tempest/common/compute.py

@@ -78,11 +78,11 @@ 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 = [{
                 'uuid': volume['volume']['id'],
                 'source_type': 'volume',
@@ -90,11 +90,10 @@ def create_test_server(clients, validatable=False, validation_resources=None,
                 'boot_index': 0,
                 'delete_on_termination': True}]
             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.
+
         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/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
-        @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,6 +29,7 @@ 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 encryption type (as admin)

tempest/scenario/test_network_basic_ops.py

@@ -374,8 +374,7 @@ 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
@@ -401,12 +400,11 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
             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,19 +443,15 @@ 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:
 
             - ping an external IP address, implying external connectivity.
-
             - ping an external hostname, implying that dns is correctly
                configured.
-
             - ping an internal IP address, implying connectivity to another
                VM on the same network.
 
@@ -466,7 +460,6 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
 
             - Ping the new VM from previous VM failed since the new network
                 was not attached to router yet.
-
             - Attach the new network to the router, Ping the new VM from
                 previous VM succeed.
 
@@ -576,6 +569,7 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
         TODO(yfried): add host_routes
 
         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
           Tempest
@@ -830,6 +824,7 @@ class TestNetworkBasicOps(manager.NetworkScenarioTest):
         required in cases where the VM routes traffic through it.
 
         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")

tempest/scenario/test_security_groups_basic_ops.py

@@ -83,8 +83,8 @@ class TestSecurityGroupsBasicOps(manager.NetworkScenarioTest):
               been created on source tenant
         7. _test_port_update_new_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,9 +93,11 @@ 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
     """

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.