doc: pytest: Document the test_bootstage test

Add this test to the documentation. We need to move the import to follow
the main comment so that it renders correctly, and add a code-block
annotation to the example and indent it correctly. Next, neither of the
functions had comments themselves, so document them now.

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

3 files changed, 37 insertions, 7 deletions

diff --git a/doc/develop/pytest/index.rst b/doc/develop/pytest/index.rst
index e2131a2f4a6..5bcda1f0952 100644
--- a/doc/develop/pytest/index.rst
+++ b/doc/develop/pytest/index.rst
@@ -18,5 +18,6 @@ Individual tests
    :maxdepth: 1
 
    test_000_version
+   test_bootstage
    test_net
    test_net_boot
diff --git a/doc/develop/pytest/test_bootstage.rst b/doc/develop/pytest/test_bootstage.rst
new file mode 100644
index 00000000000..f8f10e96a42
--- /dev/null
+++ b/doc/develop/pytest/test_bootstage.rst
@@ -0,0 +1,8 @@
+test_bootstage
+==============
+
+.. automodule:: test_bootstage
+   :synopsis:
+   :member-order: bysource
+   :members:
+   :undoc-members:
diff --git a/test/py/tests/test_bootstage.py b/test/py/tests/test_bootstage.py
index 379c1cae6dd..2505862c5a4 100644
--- a/test/py/tests/test_bootstage.py
+++ b/test/py/tests/test_bootstage.py
@@ -1,8 +1,6 @@
 # SPDX-License-Identifier: GPL-2.0
 # (C) Copyright 2023, Advanced Micro Devices, Inc.
 
-import pytest
-
 """
 Test the bootstage command.
 
@@ -15,16 +13,32 @@ common/bootstage.c). Without this, bootstage stash and unstash tests will be
 automatically skipped.
 
 For example:
-env__bootstage_cmd_file = {
-    'addr': 0x200000,
-    'size': 0x1000,
-    'bootstage_magic_addr': 0xb00757a3,
-}
+
+.. code-block:: python
+
+    env__bootstage_cmd_file = {
+        'addr': 0x200000,
+        'size': 0x1000,
+        'bootstage_magic_addr': 0xb00757a3,
+    }
 """
 
+import pytest
+
 @pytest.mark.buildconfigspec('bootstage')
 @pytest.mark.buildconfigspec('cmd_bootstage')
 def test_bootstage_report(ubman):
+    """Test the bootstage report subcommand
+
+    This will run the 'bootstage report' subcommand and ensure that we are
+    reporting:
+
+    - A timer summary in microseconds
+    - The accumulated time
+    - That at least the phrase 'dm_r' is in the output
+
+    Note that the time values are not checked.
+    """
     output = ubman.run_command('bootstage report')
     assert 'Timer summary in microseconds' in output
     assert 'Accumulated time:' in output
@@ -34,6 +48,13 @@ def test_bootstage_report(ubman):
 @pytest.mark.buildconfigspec('cmd_bootstage')
 @pytest.mark.buildconfigspec('bootstage_stash')
 def test_bootstage_stash_and_unstash(ubman):
+    """Test the bootstage stash and unstash subcommands
+
+    After checking that we have configured an environment file to use, we will
+    use the stash subcommand to save information. Then we will use the md
+    command to verify the contents in memory. Finally we confirm the unstash
+    subcommand runs successfully.
+    """
     f = ubman.config.env.get('env__bootstage_cmd_file', None)
     if not f:
         pytest.skip('No bootstage environment file is defined')