From be2bdfd0199f37fed0ce19f90840f79d185e20d1 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Wed, 7 May 2025 16:08:17 -0600 Subject: [PATCH] doc: Start improving our pytest documentation Begin the work of documenting all of our pytests. To do this, we should have a directory under develop for it as there will be a large number of new files. As the current document is referenced externally in a number of locations, add the sphinx_reredirects module so that we can redirect from the old location to the new. Signed-off-by: Tom Rini Reviewed-by: Simon Glass --- doc/conf.py | 8 +++++++- doc/develop/ci_testing.rst | 2 +- doc/develop/index.rst | 2 +- doc/develop/pytest/index.rst | 12 ++++++++++++ doc/develop/{py_testing.rst => pytest/usage.rst} | 2 +- doc/develop/testing.rst | 4 ++-- doc/develop/tests_writing.rst | 2 +- doc/sphinx/requirements.txt | 1 + 8 files changed, 26 insertions(+), 7 deletions(-) create mode 100644 doc/develop/pytest/index.rst rename doc/develop/{py_testing.rst => pytest/usage.rst} (99%) diff --git a/doc/conf.py b/doc/conf.py index c50daf874a5..3cb9b2bb65e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -47,7 +47,8 @@ needs_sphinx = '2.4.4' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel', - 'kernel_abi', 'kernel_feat', 'sphinx-prompt'] + 'kernel_abi', 'kernel_feat', 'sphinx-prompt', + 'sphinx_reredirects' ] # # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* @@ -148,6 +149,11 @@ project = 'Das U-Boot' copyright = 'The U-Boot development community' author = 'The U-Boot development community' +# Pages we have moved after being heavily referenced externally +redirects = { + "develop/py_testing": "pytest/usage.html" +} + # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. diff --git a/doc/develop/ci_testing.rst b/doc/develop/ci_testing.rst index ffaacedc3d8..2033e3447e9 100644 --- a/doc/develop/ci_testing.rst +++ b/doc/develop/ci_testing.rst @@ -18,7 +18,7 @@ be built with mingw to run on Windows. Each of the pipelines is written in such as way as to be a "world build" style test and as such we try and build all possible platforms. In addition, for all platforms that support being run in QEMU we run them in QEMU and use our pytest -suite. See :doc:`py_testing` for more information about those tests. +suite. See :doc:`pytest/usage` for more information about those tests. Azure Pipelines --------------- diff --git a/doc/develop/index.rst b/doc/develop/index.rst index c907f8c9c2c..0c83ef109ab 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -82,7 +82,7 @@ Testing :maxdepth: 1 testing - py_testing + pytest/index tests_writing tests_sandbox binman_tests diff --git a/doc/develop/pytest/index.rst b/doc/develop/pytest/index.rst new file mode 100644 index 00000000000..435d84fc619 --- /dev/null +++ b/doc/develop/pytest/index.rst @@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +pytest Framework within U-Boot +============================== + +General +------- + +.. toctree:: + :maxdepth: 1 + + usage diff --git a/doc/develop/py_testing.rst b/doc/develop/pytest/usage.rst similarity index 99% rename from doc/develop/py_testing.rst rename to doc/develop/pytest/usage.rst index deea048f771..49d269d66a7 100644 --- a/doc/develop/py_testing.rst +++ b/doc/develop/pytest/usage.rst @@ -13,7 +13,7 @@ results. Advantages of this approach are: U-Boot; there can be no disconnect. - There is no need to write or embed test-related code into U-Boot itself. It is asserted that writing test-related code in Python is simpler and more - flexible than writing it all in C. But see :doc:`tests_writing` for caveats + flexible than writing it all in C. But see :doc:`../tests_writing` for caveats and more discussion / analysis. - It is reasonably simple to interact with U-Boot in this way. diff --git a/doc/develop/testing.rst b/doc/develop/testing.rst index 9114d11ad26..aa7786c99fd 100644 --- a/doc/develop/testing.rst +++ b/doc/develop/testing.rst @@ -33,7 +33,7 @@ You can also run a selection tests in parallel with:: make pcheck All of the above use the test/run script with a paremeter to select which tests -are run. See :doc:`py_testing` for more information. +are run. See :doc:`pytest/usage` for more information. Sandbox @@ -69,7 +69,7 @@ build:: ./test/py/test.py --bd sandbox_spl --build -k test_spl -See :doc:`py_testing` for more information about the pytest suite. +See :doc:`pytest/usage` for more information about the pytest suite. See :doc:`tests_sandbox` for how to run tests directly (not through pytest). diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index f6f852c297d..062194659b5 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -376,5 +376,5 @@ An example SPL test is spl_test_load(). Writing Python tests -------------------- -See :doc:`py_testing` for brief notes how to write Python tests. You +See :doc:`pytest/usage` for brief notes how to write Python tests. You should be able to use the existing tests in test/py/tests as examples. diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 13e0327c0f6..12c5772684d 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -15,6 +15,7 @@ six==1.16.0 snowballstemmer==2.2.0 Sphinx==8.1.3 sphinx-prompt==1.9.0 +sphinx-reredirects==0.1.5 sphinx-rtd-theme==3.0.1 sphinxcontrib-applehelp==2.0.0 sphinxcontrib-devhelp==2.0.0 -- 2.39.5