[PATCH 1/3] doc: pytest: Document the test_net test

[Tom Rini]

Add this test to the documentation. While the diff appears large at
first, the only changes within the test are to move the imports to
follow the pydoc comment and then to code-block and indent the example
configuration.

Signed-off-by: Tom Rini <trini at konsulko.com>
---
Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
Cc: Simon Glass <sjg at chromium.org>
---
 doc/develop/pytest/index.rst    |   1 +
 doc/develop/pytest/test_net.rst |   8 ++
 test/py/tests/test_net.py       | 152 ++++++++++++++++----------------
 3 files changed, 86 insertions(+), 75 deletions(-)
 create mode 100644 doc/develop/pytest/test_net.rst

diff --git a/doc/develop/pytest/index.rst b/doc/develop/pytest/index.rst
index 36083882584f..e2131a2f4a68 100644
--- a/doc/develop/pytest/index.rst
+++ b/doc/develop/pytest/index.rst
@@ -18,4 +18,5 @@ Individual tests
    :maxdepth: 1
 
    test_000_version
+   test_net
    test_net_boot
diff --git a/doc/develop/pytest/test_net.rst b/doc/develop/pytest/test_net.rst
new file mode 100644
index 000000000000..571179f7b9dc
--- /dev/null
+++ b/doc/develop/pytest/test_net.rst
@@ -0,0 +1,8 @@
+test_net
+========
+
+.. automodule:: test_net
+   :synopsis:
+   :member-order: bysource
+   :members:
+   :undoc-members:
diff --git a/test/py/tests/test_net.py b/test/py/tests/test_net.py
index 4732e4b57f8a..27cdd73fd49c 100644
--- a/test/py/tests/test_net.py
+++ b/test/py/tests/test_net.py
@@ -4,12 +4,6 @@
 # Test various network-related functionality, such as the dhcp, ping, and
 # tftpboot commands.
 
-import pytest
-import utils
-import uuid
-import datetime
-import re
-
 """
 Note: This test relies on boardenv_* containing configuration values to define
 which network environment is available for testing. Without this, this test
@@ -17,77 +11,85 @@ will be automatically skipped.
 
 For example:
 
-# Boolean indicating whether the Ethernet device is attached to USB, and hence
-# USB enumeration needs to be performed prior to network tests.
-# This variable may be omitted if its value is False.
-env__net_uses_usb = False
-
-# Boolean indicating whether the Ethernet device is attached to PCI, and hence
-# PCI enumeration needs to be performed prior to network tests.
-# This variable may be omitted if its value is False.
-env__net_uses_pci = True
-
-# True if a DHCP server is attached to the network, and should be tested.
-# If DHCP testing is not possible or desired, this variable may be omitted or
-# set to False.
-env__net_dhcp_server = True
-
-# False or omitted if a DHCP server is attached to the network, and dhcp abort
-# case should be tested.
-# If DHCP abort testing is not possible or desired, set this variable to True.
-# For example: On some setup, dhcp is too fast and this case may not work.
-env__dhcp_abort_test_skip = True
-
-# True if a DHCPv6 server is attached to the network, and should be tested.
-# If DHCPv6 testing is not possible or desired, this variable may be omitted or
-# set to False.
-env__net_dhcp6_server = True
-
-# A list of environment variables that should be set in order to configure a
-# static IP. If solely relying on DHCP, this variable may be omitted or set to
-# an empty list.
-env__net_static_env_vars = [
-    ('ipaddr', '10.0.0.100'),
-    ('netmask', '255.255.255.0'),
-    ('serverip', '10.0.0.1'),
-]
-
-# Details regarding a file that may be read from a TFTP server. This variable
-# may be omitted or set to None if TFTP testing is not possible or desired.
-env__net_tftp_readable_file = {
-    'fn': 'ubtest-readable.bin',
-    'addr': 0x10000000,
-    'size': 5058624,
-    'crc32': 'c2244b26',
-    'timeout': 50000,
-    'fnu': 'ubtest-upload.bin',
-}
-
-# Details regarding a file that may be read from a NFS server. This variable
-# may be omitted or set to None if NFS testing is not possible or desired.
-env__net_nfs_readable_file = {
-    'fn': 'ubtest-readable.bin',
-    'addr': 0x10000000,
-    'size': 5058624,
-    'crc32': 'c2244b26',
-}
-
-# Details regarding a file that may be read from a TFTP server. This variable
-# may be omitted or set to None if PXE testing is not possible or desired.
-env__net_pxe_readable_file = {
-    'fn': 'default',
-    'addr': 0x2000000,
-    'size': 74,
-    'timeout': 50000,
-    'pattern': 'Linux',
-}
-
-# True if a router advertisement service is connected to the network, and should
-# be tested. If router advertisement testing is not possible or desired, this
-variable may be omitted or set to False.
-env__router_on_net = True
+.. code-block:: python
+
+    # Boolean indicating whether the Ethernet device is attached to USB, and hence
+    # USB enumeration needs to be performed prior to network tests.
+    # This variable may be omitted if its value is False.
+    env__net_uses_usb = False
+
+    # Boolean indicating whether the Ethernet device is attached to PCI, and hence
+    # PCI enumeration needs to be performed prior to network tests.
+    # This variable may be omitted if its value is False.
+    env__net_uses_pci = True
+
+    # True if a DHCP server is attached to the network, and should be tested.
+    # If DHCP testing is not possible or desired, this variable may be omitted or
+    # set to False.
+    env__net_dhcp_server = True
+
+    # False or omitted if a DHCP server is attached to the network, and dhcp abort
+    # case should be tested.
+    # If DHCP abort testing is not possible or desired, set this variable to True.
+    # For example: On some setup, dhcp is too fast and this case may not work.
+    env__dhcp_abort_test_skip = True
+
+    # True if a DHCPv6 server is attached to the network, and should be tested.
+    # If DHCPv6 testing is not possible or desired, this variable may be omitted or
+    # set to False.
+    env__net_dhcp6_server = True
+
+    # A list of environment variables that should be set in order to configure a
+    # static IP. If solely relying on DHCP, this variable may be omitted or set to
+    # an empty list.
+    env__net_static_env_vars = [
+        ('ipaddr', '10.0.0.100'),
+        ('netmask', '255.255.255.0'),
+        ('serverip', '10.0.0.1'),
+    ]
+
+    # Details regarding a file that may be read from a TFTP server. This variable
+    # may be omitted or set to None if TFTP testing is not possible or desired.
+    env__net_tftp_readable_file = {
+        'fn': 'ubtest-readable.bin',
+        'addr': 0x10000000,
+        'size': 5058624,
+        'crc32': 'c2244b26',
+        'timeout': 50000,
+        'fnu': 'ubtest-upload.bin',
+    }
+
+    # Details regarding a file that may be read from a NFS server. This variable
+    # may be omitted or set to None if NFS testing is not possible or desired.
+    env__net_nfs_readable_file = {
+        'fn': 'ubtest-readable.bin',
+        'addr': 0x10000000,
+        'size': 5058624,
+        'crc32': 'c2244b26',
+    }
+
+    # Details regarding a file that may be read from a TFTP server. This variable
+    # may be omitted or set to None if PXE testing is not possible or desired.
+    env__net_pxe_readable_file = {
+        'fn': 'default',
+        'addr': 0x2000000,
+        'size': 74,
+        'timeout': 50000,
+        'pattern': 'Linux',
+    }
+
+    # True if a router advertisement service is connected to the network, and should
+    # be tested. If router advertisement testing is not possible or desired, this
+    variable may be omitted or set to False.
+    env__router_on_net = True
 """
 
+import pytest
+import utils
+import uuid
+import datetime
+import re
+
 net_set_up = False
 net6_set_up = False
 
-- 
2.43.0