Add test documentation for docs tox target

Enable sphinx to generate documentation from docstrings by running
'tox -e docs'.

Change-Id: I5996e5f07493f69f14172b4bb0535852e89d5456

.gitignore

@@ -43,6 +43,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
+doc/source/tests
 
 # pbr generates these
 AUTHORS

doc/source/conf.py

@@ -15,7 +15,14 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('../..'))
+def autodoc_skip_member_handler(app, what, name, obj, skip, options):
+    return skip or (what == "class" and not name.startswith("test"))
+
+def setup(app):
+    app.connect('autodoc-skip-member', autodoc_skip_member_handler)
+
+sys.path.insert(0, os.path.abspath('../../neutron_tempest_plugin'))
+
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be

doc/source/index.rst

@@ -15,6 +15,7 @@ Contents:
    readme
    installation
    contributing
+   test_descriptions
 
 Indices and tables
 ==================

doc/source/test_descriptions.rst

@@ -0,0 +1,7 @@
+Description of Tests
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   tests/modules

neutron_tempest_plugin/common/shell.py

@@ -47,18 +47,18 @@ def execute(command, ssh_client=None, timeout=None, check=True):
     :param timeout: command execution timeout in seconds
 
     :param check: when False it doesn't raises ShellCommandFailed when
-    exit status is not zero. True by default
+       exit status is not zero. True by default
 
     :returns: STDOUT text when command execution terminates with zero exit
-    status.
+       status.
 
     :raises ShellTimeoutExpired: when timeout expires before command execution
-    terminates. In such case it kills the process, then it eventually would
+       terminates. In such case it kills the process, then it eventually would
-    try to read STDOUT and STDERR buffers (not fully implemented) before
+       try to read STDOUT and STDERR buffers (not fully implemented) before
-    raising the exception.
+       raising the exception.
 
     :raises ShellCommandFailed: when command execution terminates with non-zero
-    exit status.
+       exit status.
     """
     ssh_client = ssh_client or SSH_PROXY_CLIENT
     if timeout:

neutron_tempest_plugin/common/ssh.py

@@ -133,7 +133,7 @@ class Client(ssh.Client):
         :returns: paramiko.Client connected to remote server.
 
         :raises tempest.lib.exceptions.SSHTimeout: in case it fails to connect
-        to remote server.
+           to remote server.
         """
         return super(Client, self)._get_ssh_connection(*args, **kwargs)
 

neutron_tempest_plugin/common/utils.py

@@ -73,7 +73,7 @@ def wait_until_true(predicate, timeout=60, sleep=1, exception=None):
     """Wait until callable predicate is evaluated as True
 
     :param predicate: Callable deciding whether waiting should continue.
-    Best practice is to instantiate predicate with functools.partial()
+       Best practice is to instantiate predicate with functools.partial()
     :param timeout: Timeout in seconds how long should function wait.
     :param sleep: Polling interval for results in seconds.
     :param exception: Exception instance to raise on timeout. If None is passed

neutron_tempest_plugin/neutron_dynamic_routing/scenario/test_simple_bgp.py

@@ -68,24 +68,26 @@ class BgpClientMixin(object):
 class Bgp(BgpClientMixin, base.BaseTempestTestCase):
     """Test the following topology
 
-          +-------------------+
+    .. code-block:: HTML
-          | public            |
+
-          | network           |
+              +-------------------+
-          |                   |
+              | public            |
-          +-+---------------+-+
+              | network           |
-            |               |
+              |                   |
-            |               |
+              +-+---------------+-+
-    +-------+-+           +-+-------+
+                |               |
-    | LEFT    |           | RIGHT   |
+                |               |
-    | router  | <--BGP--> | router  |
+        +-------+-+           +-+-------+
-    |         |           |         |
+        | LEFT    |           | RIGHT   |
-    +----+----+           +----+----+
+        | router  | <--BGP--> | router  |
-         |                     |
+        |         |           |         |
-    +----+----+           +----+----+
+        +----+----+           +----+----+
-    | LEFT    |           | RIGHT   |
+             |                     |
-    | network |           | network |
+        +----+----+           +----+----+
-    |         |           |         |
+        | LEFT    |           | RIGHT   |
-    +---------+           +---------+
+        | network |           | network |
+        |         |           |         |
+        +---------+           +---------+
     """
 
     credentials = ['primary', 'admin']

neutron_tempest_plugin/scenario/test_connectivity.py

@@ -173,18 +173,21 @@ class NetworkConnectivityTest(base.BaseTempestTestCase):
         ensures that connectivity from VM to both routers is working.
 
         Test scenario: (NOTE: 10.1.0.0/24 private CIDR is used as an example)
-        +----------------+                  +------------+
+
-        | Non-dvr router |                  | DVR router |
+        .. code-block:: HTML
-        |                |                  |            |
+
-        |    10.1.0.1    |                  |  10.1.0.x  |
+            +----------------+                  +------------+
-        +-------+--------+                  +-----+------+
+            | Non-dvr router |                  | DVR router |
-                |                                 |
+            |                |                  |            |
-                |         10.1.0.0/24             |
+            |    10.1.0.1    |                  |  10.1.0.x  |
-                +----------------+----------------+
+            +-------+--------+                  +-----+------+
-                                 |
+                    |                                 |
-                               +-+-+
+                    |         10.1.0.0/24             |
-                               |VM |
+                    +----------------+----------------+
-                               +---+
+                                     |
+                                   +-+-+
+                                   |VM |
+                                   +---+
 
         where:
         10.1.0.1 - is subnet's gateway IP address,

neutron_tempest_plugin/scenario/test_floatingip.py

@@ -607,7 +607,7 @@ class FloatingIpMultipleRoutersTest(base.BaseTempestTestCase):
                deleted just before the creation of the new IP to "reserve" the
                IP address associated (see LP#1880976).
             10. Create a FIP for the VM3 in the external network with
-               the same IP address that was used for VM2.
+                the same IP address that was used for VM2.
             11. Make sure that now VM1 is able to reach VM3 using the FIP.
 
         Note, the scenario passes only in case corresponding

neutron_tempest_plugin/scenario/test_internal_dns.py

@@ -89,8 +89,8 @@ class InternalDNSTest(InternalDNSBase):
 
         1) Create two VMs on the same network, giving each a name
         2) SSH in to the first VM:
-          2.1) ping the other VM's internal IP
+            - ping the other VM's internal IP
-          2.2) ping the other VM's hostname
+            - ping the other VM's hostname
         """
         network = self.create_network(dns_domain='starwars.')
         self.setup_network_and_server(network=network, server_name='luke')

neutron_tempest_plugin/vpnaas/api/test_vpnaas.py

@@ -34,9 +34,10 @@ class VPNaaSTestJSON(base.BaseAdminNetworkTest):
 
     Tests the following operations in the Neutron API using the REST client for
     Neutron:
-        List, Show, Create, Delete, and Update VPN Service
+
-        List, Show, Create, Delete, and Update IKE policy
+        * List, Show, Create, Delete, and Update VPN Service
-        List, Show, Create, Delete, and Update IPSec policy
+        * List, Show, Create, Delete, and Update IKE policy
+        * List, Show, Create, Delete, and Update IPSec policy
     """
 
     @classmethod

neutron_tempest_plugin/vpnaas/scenario/test_vpnaas.py

@@ -52,24 +52,26 @@ CONF.register_opt(
 class Vpnaas(base.BaseTempestTestCase):
     """Test the following topology
 
-          +-------------------+
+    .. code-block:: HTML
-          | public            |
+
-          | network           |
+              +-------------------+
-          |                   |
+              | public            |
-          +-+---------------+-+
+              | network           |
-            |               |
+              |                   |
-            |               |
+              +-+---------------+-+
-    +-------+-+           +-+-------+
+                |               |
-    | LEFT    |           | RIGHT   |
+                |               |
-    | router  | <--VPN--> | router  |
+        +-------+-+           +-+-------+
-    |         |           |         |
+        | LEFT    |           | RIGHT   |
-    +----+----+           +----+----+
+        | router  | <--VPN--> | router  |
-         |                     |
+        |         |           |         |
-    +----+----+           +----+----+
+        +----+----+           +----+----+
-    | LEFT    |           | RIGHT   |
+             |                     |
-    | network |           | network |
+        +----+----+           +----+----+
-    |         |           |         |
+        | LEFT    |           | RIGHT   |
-    +---------+           +---------+
+        | network |           | network |
+        |         |           |         |
+        +---------+           +---------+
     """
 
     credentials = ['primary', 'admin']

tox.ini

@@ -40,8 +40,15 @@ commands =
 
 [testenv:docs]
 deps = -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
+       -r{toxinidir}/requirements.txt
        -r{toxinidir}/doc/requirements.txt
-commands = sphinx-build -W -b html doc/source doc/build/html
+commands =
+  rm -rf doc/source/tests
+  sphinx-apidoc -f -o doc/source/tests neutron_tempest_plugin
+  rm -rf doc/build
+  sphinx-build -W -b html doc/source doc/build/html
+allowlist_externals =
+    rm
 
 [testenv:releasenotes]
 deps = {[testenv:docs]deps}