From a865d1d25410af97376fd3c822bac560b99fd84b Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Wed, 7 May 2025 16:08:18 -0600 Subject: [PATCH] doc: pytest: Framework for documenting tests and document test_000_version 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 Reviewed-by: Simon Glass --- .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 5e1938b0526..9c136513bb9 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 6f11331514b..7aadd5d8b73 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 15c7e633b87..bd136a48982 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 3cb9b2bb65e..84d028feda8 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 435d84fc619..ca45e157d3b 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 00000000000..09e9a361729 --- /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 b95ceae2346..63d392e956e 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.39.5