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 <trini@konsulko.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
diff --git a/doc/conf.py b/doc/conf.py
index c50daf8..3cb9b2b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -47,7 +47,8 @@
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 @@
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 ffaaced..2033e34 100644
--- a/doc/develop/ci_testing.rst
+++ b/doc/develop/ci_testing.rst
@@ -18,7 +18,7 @@
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 c907f8c..0c83ef1 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -82,7 +82,7 @@
: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 0000000..435d84f
--- /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 98%
rename from doc/develop/py_testing.rst
rename to doc/develop/pytest/usage.rst
index deea048..49d269d 100644
--- a/doc/develop/py_testing.rst
+++ b/doc/develop/pytest/usage.rst
@@ -13,7 +13,7 @@
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 9114d11..aa7786c 100644
--- a/doc/develop/testing.rst
+++ b/doc/develop/testing.rst
@@ -33,7 +33,7 @@
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 @@
./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 f6f852c..0621946 100644
--- a/doc/develop/tests_writing.rst
+++ b/doc/develop/tests_writing.rst
@@ -376,5 +376,5 @@
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 13e0327..12c5772 100644
--- a/doc/sphinx/requirements.txt
+++ b/doc/sphinx/requirements.txt
@@ -15,6 +15,7 @@
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