From f2e985e8fd923636e6bc724c6767b323c396a9ad Mon Sep 17 00:00:00 2001 From: Elod Illes Date: Mon, 6 Nov 2023 19:30:29 +0100 Subject: [PATCH] Add test documentation for docs tox target Enable sphinx to generate documentation from docstrings by running 'tox -e docs'. Change-Id: I5996e5f07493f69f14172b4bb0535852e89d5456 --- .gitignore | 3 +- doc/source/conf.py | 9 ++++- doc/source/index.rst | 1 + doc/source/test_descriptions.rst | 7 ++++ neutron_tempest_plugin/common/shell.py | 12 +++--- neutron_tempest_plugin/common/ssh.py | 2 +- neutron_tempest_plugin/common/utils.py | 2 +- .../scenario/test_simple_bgp.py | 38 ++++++++++--------- .../scenario/test_connectivity.py | 27 +++++++------ .../scenario/test_floatingip.py | 2 +- .../scenario/test_internal_dns.py | 4 +- .../vpnaas/api/test_vpnaas.py | 7 ++-- .../vpnaas/scenario/test_vpnaas.py | 38 ++++++++++--------- tox.ini | 9 ++++- 14 files changed, 96 insertions(+), 65 deletions(-) create mode 100644 doc/source/test_descriptions.rst diff --git a/.gitignore b/.gitignore index 228b0a82..1ce41cd3 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,7 @@ output/*/index.html # Sphinx doc/build +doc/source/tests # pbr generates these AUTHORS @@ -54,4 +55,4 @@ ChangeLog .*sw? # Files created by releasenotes build -releasenotes/build \ No newline at end of file +releasenotes/build diff --git a/doc/source/conf.py b/doc/source/conf.py index 2349713a..88b97183 100755 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 91388a94..e69a4ec3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,6 +15,7 @@ Contents: readme installation contributing + test_descriptions Indices and tables ================== diff --git a/doc/source/test_descriptions.rst b/doc/source/test_descriptions.rst new file mode 100644 index 00000000..240e4485 --- /dev/null +++ b/doc/source/test_descriptions.rst @@ -0,0 +1,7 @@ +Description of Tests +==================== + +.. toctree:: + :maxdepth: 2 + + tests/modules diff --git a/neutron_tempest_plugin/common/shell.py b/neutron_tempest_plugin/common/shell.py index eebb07d7..073bf55d 100644 --- a/neutron_tempest_plugin/common/shell.py +++ b/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 - try to read STDOUT and STDERR buffers (not fully implemented) before - raising the exception. + terminates. In such case it kills the process, then it eventually would + try to read STDOUT and STDERR buffers (not fully implemented) before + 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: diff --git a/neutron_tempest_plugin/common/ssh.py b/neutron_tempest_plugin/common/ssh.py index 4cb14746..700d21b1 100644 --- a/neutron_tempest_plugin/common/ssh.py +++ b/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) diff --git a/neutron_tempest_plugin/common/utils.py b/neutron_tempest_plugin/common/utils.py index ab99db9f..c62aa789 100644 --- a/neutron_tempest_plugin/common/utils.py +++ b/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 diff --git a/neutron_tempest_plugin/neutron_dynamic_routing/scenario/test_simple_bgp.py b/neutron_tempest_plugin/neutron_dynamic_routing/scenario/test_simple_bgp.py index fe0f3fcb..a7bc12af 100644 --- a/neutron_tempest_plugin/neutron_dynamic_routing/scenario/test_simple_bgp.py +++ b/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 - +-------------------+ - | public | - | network | - | | - +-+---------------+-+ - | | - | | - +-------+-+ +-+-------+ - | LEFT | | RIGHT | - | router | <--BGP--> | router | - | | | | - +----+----+ +----+----+ - | | - +----+----+ +----+----+ - | LEFT | | RIGHT | - | network | | network | - | | | | - +---------+ +---------+ + .. code-block:: HTML + + +-------------------+ + | public | + | network | + | | + +-+---------------+-+ + | | + | | + +-------+-+ +-+-------+ + | LEFT | | RIGHT | + | router | <--BGP--> | router | + | | | | + +----+----+ +----+----+ + | | + +----+----+ +----+----+ + | LEFT | | RIGHT | + | network | | network | + | | | | + +---------+ +---------+ """ credentials = ['primary', 'admin'] diff --git a/neutron_tempest_plugin/scenario/test_connectivity.py b/neutron_tempest_plugin/scenario/test_connectivity.py index 5608daeb..a6fc8938 100644 --- a/neutron_tempest_plugin/scenario/test_connectivity.py +++ b/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 | - | | | | - | 10.1.0.1 | | 10.1.0.x | - +-------+--------+ +-----+------+ - | | - | 10.1.0.0/24 | - +----------------+----------------+ - | - +-+-+ - |VM | - +---+ + + .. code-block:: HTML + + +----------------+ +------------+ + | Non-dvr router | | DVR router | + | | | | + | 10.1.0.1 | | 10.1.0.x | + +-------+--------+ +-----+------+ + | | + | 10.1.0.0/24 | + +----------------+----------------+ + | + +-+-+ + |VM | + +---+ where: 10.1.0.1 - is subnet's gateway IP address, diff --git a/neutron_tempest_plugin/scenario/test_floatingip.py b/neutron_tempest_plugin/scenario/test_floatingip.py index a5f6486b..804683d6 100644 --- a/neutron_tempest_plugin/scenario/test_floatingip.py +++ b/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 diff --git a/neutron_tempest_plugin/scenario/test_internal_dns.py b/neutron_tempest_plugin/scenario/test_internal_dns.py index e705241b..9ffb05d6 100644 --- a/neutron_tempest_plugin/scenario/test_internal_dns.py +++ b/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') diff --git a/neutron_tempest_plugin/vpnaas/api/test_vpnaas.py b/neutron_tempest_plugin/vpnaas/api/test_vpnaas.py index 953360ef..b61fb1bc 100644 --- a/neutron_tempest_plugin/vpnaas/api/test_vpnaas.py +++ b/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 diff --git a/neutron_tempest_plugin/vpnaas/scenario/test_vpnaas.py b/neutron_tempest_plugin/vpnaas/scenario/test_vpnaas.py index 92eed9e6..c7b64d5a 100644 --- a/neutron_tempest_plugin/vpnaas/scenario/test_vpnaas.py +++ b/neutron_tempest_plugin/vpnaas/scenario/test_vpnaas.py @@ -52,24 +52,26 @@ CONF.register_opt( class Vpnaas(base.BaseTempestTestCase): """Test the following topology - +-------------------+ - | public | - | network | - | | - +-+---------------+-+ - | | - | | - +-------+-+ +-+-------+ - | LEFT | | RIGHT | - | router | <--VPN--> | router | - | | | | - +----+----+ +----+----+ - | | - +----+----+ +----+----+ - | LEFT | | RIGHT | - | network | | network | - | | | | - +---------+ +---------+ + .. code-block:: HTML + + +-------------------+ + | public | + | network | + | | + +-+---------------+-+ + | | + | | + +-------+-+ +-+-------+ + | LEFT | | RIGHT | + | router | <--VPN--> | router | + | | | | + +----+----+ +----+----+ + | | + +----+----+ +----+----+ + | LEFT | | RIGHT | + | network | | network | + | | | | + +---------+ +---------+ """ credentials = ['primary', 'admin'] diff --git a/tox.ini b/tox.ini index c2fc078c..2f7da5c3 100644 --- a/tox.ini +++ b/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}