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/neutron_dynamic_routing/scenario/test_simple_bgp.py

@@ -68,6 +68,8 @@ class BgpClientMixin(object):
 class Bgp(BgpClientMixin, base.BaseTempestTestCase):
     """Test the following topology
 
+    .. code-block:: HTML
+
               +-------------------+
               | public            |
               | network           |

neutron_tempest_plugin/scenario/test_connectivity.py

@@ -173,6 +173,9 @@ 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)
+
+        .. code-block:: HTML
+
             +----------------+                  +------------+
             | Non-dvr router |                  | DVR router |
             |                |                  |            |

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
-          2.2) ping the other VM's hostname
+            - ping the other VM's internal IP
+            - 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 IPSec policy
+
+        * List, Show, Create, Delete, and Update VPN Service
+        * 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,6 +52,8 @@ CONF.register_opt(
 class Vpnaas(base.BaseTempestTestCase):
     """Test the following topology
 
+    .. code-block:: HTML
+
               +-------------------+
               | public            |
               | network           |

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}