doc: pytest: Document the test_net_boot test

Add the test_net_boot.py test to the generated documentation. While most
of this was already commented correctly for inclusion the biggest
problem was examples of code without a code-block notation. This in turn
broke parsing. Add the missing notations. We also must have the comment
prior to any import lines or it will not be seen as a comment on the
overall file and thus not included.

Signed-off-by: Tom Rini <trini@konsulko.com>
Reviewed-by: Simon Glass <sjg@chromium.org>

diff --git a/doc/develop/pytest/index.rst b/doc/develop/pytest/index.rst
index ca45e157d3beb44e70e26090cea3d89ee176bab2..36083882584fcba50521ca2ad700fbf6b3a29203 100644 (file)
--- a/doc/develop/pytest/index.rst
+++ b/doc/develop/pytest/index.rst
@@ -18,3 +18,4 @@ Individual tests
    :maxdepth: 1
 
    test_000_version
+   test_net_boot

diff --git a/doc/develop/pytest/test_net_boot.rst b/doc/develop/pytest/test_net_boot.rst
new file mode 100644 (file)
index 0000000..369bd3b
--- /dev/null
+++ b/doc/develop/pytest/test_net_boot.rst
@@ -0,0 +1,8 @@
+test_net_boot
+=============
+
+.. automodule:: test_net_boot
+   :synopsis:
+   :member-order: bysource
+   :members:
+   :undoc-members:

diff --git a/test/py/tests/test_net_boot.py b/test/py/tests/test_net_boot.py
index abf6dfbaf5e4bb8aca5bbfeef3badfeb83d67e00..6585f0574c01d305394496ec3a28c45bcbae1c08 100644 (file)
--- a/test/py/tests/test_net_boot.py
+++ b/test/py/tests/test_net_boot.py
@@ -1,11 +1,6 @@
 # SPDX-License-Identifier: GPL-2.0
 # (C) Copyright 2023, Advanced Micro Devices, Inc.
 
-import pytest
-import utils
-import test_net
-import re
-
 """
 Note: This test relies on boardenv_* containing configuration values to define
 which the network environment available for testing. Without this, this test
@@ -13,77 +8,88 @@ will be automatically skipped.
 
 For example:
 
-# Details regarding a boot image file that may be read from a TFTP server. This
-# variable may be omitted or set to None if TFTP boot testing is not possible
-# or desired.
-env__net_tftp_bootable_file = {
-    'fn': 'image.ub',
-    'addr': 0x10000000,
-    'size': 5058624,
-    'crc32': 'c2244b26',
-    'pattern': 'Linux',
-    'config': 'config@2',
-    'timeout': 50000,
-    'check_type': 'boot_error',
-    'check_pattern': 'ERROR',
-}
-
-# False or omitted if a TFTP boot test should be tested.
-# If TFTP boot testing is not possible or desired, set this variable to True.
-# For example: If FIT image is not proper to boot
-env__tftp_boot_test_skip = False
-
-# Here is the example of FIT image configurations:
-configurations {
-    default = "config@1";
-    config@1 {
-        description = "Boot Linux kernel with config@1";
-        kernel = "kernel@0";
-        fdt = "fdt@0";
-        ramdisk = "ramdisk@0";
-        hash@1 {
-            algo = "sha1";
-        };
-    };
-    config@2 {
-        description = "Boot Linux kernel with config@2";
-        kernel = "kernel@1";
-        fdt = "fdt@1";
-        ramdisk = "ramdisk@1";
-        hash@1 {
-            algo = "sha1";
-        };
-    };
-};
-
-# 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_bootable_file = {
-    'fn': 'default',
-    'addr': 0x10000000,
-    'size': 74,
-    'timeout': 50000,
-    'pattern': 'Linux',
-    'valid_label': '1',
-    'invalid_label': '2',
-    'exp_str_invalid': 'Skipping install for failure retrieving',
-    'local_label': '3',
-    'exp_str_local': 'missing environment variable: localcmd',
-    'empty_label': '4',
-    'exp_str_empty': 'No kernel given, skipping boot',
-    'check_type': 'boot_error',
-    'check_pattern': 'ERROR',
-}
-
-# False if a PXE boot test should be tested.
-# If PXE boot testing is not possible or desired, set this variable to True.
-# For example: If pxe configuration file is not proper to boot
-env__pxe_boot_test_skip = False
-
-# Here is the example of pxe configuration file ordered based on the execution
-# flow:
+.. code-block:: python
+
+   # Details regarding a boot image file that may be read from a TFTP server. This
+   # variable may be omitted or set to None if TFTP boot testing is not possible
+   # or desired.
+   env__net_tftp_bootable_file = {
+       'fn': 'image.ub',
+       'addr': 0x10000000,
+       'size': 5058624,
+       'crc32': 'c2244b26',
+       'pattern': 'Linux',
+       'config': 'config@2',
+       'timeout': 50000,
+       'check_type': 'boot_error',
+       'check_pattern': 'ERROR',
+   }
+
+   # False or omitted if a TFTP boot test should be tested.
+   # If TFTP boot testing is not possible or desired, set this variable to True.
+   # For example: If FIT image is not proper to boot
+   env__tftp_boot_test_skip = False
+
+
+Here is the example of FIT image configurations:
+
+.. code-block:: devicetree
+
+   configurations {
+       default = "config@1";
+       config@1 {
+           description = "Boot Linux kernel with config@1";
+           kernel = "kernel@0";
+           fdt = "fdt@0";
+           ramdisk = "ramdisk@0";
+           hash@1 {
+               algo = "sha1";
+           };
+       };
+       config@2 {
+           description = "Boot Linux kernel with config@2";
+           kernel = "kernel@1";
+           fdt = "fdt@1";
+           ramdisk = "ramdisk@1";
+           hash@1 {
+               algo = "sha1";
+           };
+       };
+   };
+
+.. code-block:: python
+
+   # 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_bootable_file = {
+       'fn': 'default',
+       'addr': 0x10000000,
+       'size': 74,
+       'timeout': 50000,
+       'pattern': 'Linux',
+       'valid_label': '1',
+       'invalid_label': '2',
+       'exp_str_invalid': 'Skipping install for failure retrieving',
+       'local_label': '3',
+       'exp_str_local': 'missing environment variable: localcmd',
+       'empty_label': '4',
+       'exp_str_empty': 'No kernel given, skipping boot',
+       'check_type': 'boot_error',
+       'check_pattern': 'ERROR',
+   }
+
+   # False if a PXE boot test should be tested.
+   # If PXE boot testing is not possible or desired, set this variable to True.
+   # For example: If pxe configuration file is not proper to boot
+   env__pxe_boot_test_skip = False
+
+Here is the example of pxe configuration file ordered based on the execution
+flow:
+
 1) /tftpboot/pxelinux.cfg/default-arm-zynqmp
 
+.. code-block::
+
     menu include pxelinux.cfg/default-arm
     timeout 50
 
@@ -91,6 +97,8 @@ env__pxe_boot_test_skip = False
 
 2) /tftpboot/pxelinux.cfg/default-arm
 
+.. code-block::
+
     menu title Linux boot selections
     menu include pxelinux.cfg/default
 
@@ -110,6 +118,8 @@ env__pxe_boot_test_skip = False
 
 3) /tftpboot/pxelinux.cfg/default
 
+.. code-block::
+
     label Linux
         menu label Boot kernel
         kernel Image
@@ -117,6 +127,11 @@ env__pxe_boot_test_skip = False
         initrd rootfs.cpio.gz.u-boot
 """
 
+import pytest
+import utils
+import test_net
+import re
+
 def setup_networking(ubman):
     test_net.test_net_dhcp(ubman)
     if not test_net.net_set_up: