[PATCH v2 2/4] doc: pytest: Framework for documenting tests and document test_000_version

[Tom Rini]

In order to easily document pytests, we need to include the autodoc
extension. We also need to make sure that for building the docs, CI
includes pytest and that we have PYTHONPATH configured such that it will
find all of the tests and related files. Finally, we need to have our
comments in the test file by in proper pydoc format in order to be
included in the output.

Signed-off-by: Tom Rini <trini at konsulko.com>
---
Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
Cc: Simon Glass <sjg at chromium.org>
---
 .azure-pipelines.yml                    |  2 +-
 .gitlab-ci.yml                          |  2 +-
 Makefile                                |  3 ++-
 doc/conf.py                             |  2 +-
 doc/develop/pytest/index.rst            |  8 ++++++++
 doc/develop/pytest/test_000_version.rst |  8 ++++++++
 test/py/tests/test_000_version.py       | 10 ++++++----
 7 files changed, 27 insertions(+), 8 deletions(-)
 create mode 100644 doc/develop/pytest/test_000_version.rst

diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml
index 5e1938b05262..9c136513bb9e 100644
--- a/.azure-pipelines.yml
+++ b/.azure-pipelines.yml
@@ -92,7 +92,7 @@ stages:
           set -e
           python3 -m venv /tmp/venvhtml
           . /tmp/venvhtml/bin/activate
-          pip install -r doc/sphinx/requirements.txt
+          pip install -r doc/sphinx/requirements.txt pytest
           make htmldocs KDOC_WERROR=1
           make infodocs
 
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 6f11331514b8..7aadd5d8b735 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -164,7 +164,7 @@ docs:
   script:
     - python3 -m venv /tmp/venvhtml
     - . /tmp/venvhtml/bin/activate
-    - pip install -r doc/sphinx/requirements.txt
+    - pip install -r doc/sphinx/requirements.txt pytest
     - make htmldocs KDOC_WERROR=1
     - make infodocs
 
diff --git a/Makefile b/Makefile
index 15c7e633b874..bd136a48982a 100644
--- a/Makefile
+++ b/Makefile
@@ -2448,7 +2448,8 @@ DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
 	       linkcheckdocs dochelp refcheckdocs texinfodocs infodocs
 PHONY += $(DOC_TARGETS)
 $(DOC_TARGETS): scripts_basic FORCE
-	$(Q)$(MAKE) $(build)=doc $@
+	$(Q)PYTHONPATH=$(srctree)/test/py/tests:$(srctree)/test/py \
+	$(MAKE) $(build)=doc $@
 
 PHONY += checkstack ubootrelease ubootversion
 
diff --git a/doc/conf.py b/doc/conf.py
index 3cb9b2bb65e5..84d028feda83 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -48,7 +48,7 @@ extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
               'kernel_abi', 'kernel_feat', 'sphinx-prompt',
-              'sphinx_reredirects' ]
+              'sphinx_reredirects', 'sphinx.ext.autodoc' ]
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
diff --git a/doc/develop/pytest/index.rst b/doc/develop/pytest/index.rst
index 435d84fc619f..ca45e157d3be 100644
--- a/doc/develop/pytest/index.rst
+++ b/doc/develop/pytest/index.rst
@@ -10,3 +10,11 @@ General
    :maxdepth: 1
 
    usage
+
+Individual tests
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   test_000_version
diff --git a/doc/develop/pytest/test_000_version.rst b/doc/develop/pytest/test_000_version.rst
new file mode 100644
index 000000000000..09e9a361729b
--- /dev/null
+++ b/doc/develop/pytest/test_000_version.rst
@@ -0,0 +1,8 @@
+test_000_version
+================
+
+.. automodule:: test_000_version
+   :synopsis:
+   :member-order: bysource
+   :members:
+   :undoc-members:
diff --git a/test/py/tests/test_000_version.py b/test/py/tests/test_000_version.py
index b95ceae23465..63d392e956e0 100644
--- a/test/py/tests/test_000_version.py
+++ b/test/py/tests/test_000_version.py
@@ -2,10 +2,12 @@
 # Copyright (c) 2015 Stephen Warren
 # Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
 
-# pytest runs tests the order of their module path, which is related to the
-# filename containing the test. This file is named such that it is sorted
-# first, simply as a very basic sanity check of the functionality of the U-Boot
-# command prompt.
+"""
+pytest runs tests the order of their module path, which is related to the
+filename containing the test. This file is named such that it is sorted
+first, simply as a very basic sanity check of the functionality of the U-Boot
+command prompt.
+"""
 
 def test_version(ubman):
     """Test that the "version" command prints the U-Boot version."""
-- 
2.43.0