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 c50daf874a53d6720907b14ff63238f654f2b0bb..3cb9b2bb65e59c7081409a7c386c67c29a709223 100644 (file)
--- 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 ffaacedc3d888e593cd132d89dd1b2426c7ed36e..2033e3447e9ef24a08855791f3aa1941dbe38b95 100644 (file)
--- 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 c907f8c9c2c0ce63d5a3e23dc77ff334b840ceff..0c83ef109ab89050e5453393502defbecea92355 100644 (file)
--- 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 (file)
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 99%
rename from doc/develop/py_testing.rst
rename to doc/develop/pytest/usage.rst
index deea048f7712717e97f234bbf0707a5191cabfc0..49d269d66a709438e589b7b09d904bca2f023a1e 100644 (file)
--- 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 9114d11ad26d7e1fe54006f6d6249358da7c6f7c..aa7786c99fd54e775426164addd8025c73926a4a 100644 (file)
--- 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 f6f852c297df4a747bc4d74e0beed8d94c837d2e..062194659b5afb956f8004970c4a14039dfac15e 100644 (file)
--- 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 13e0327c0f674105e94c382d85402a2c165d740f..12c5772684dc57af5e640f67be27a5c7c67ad847 100644 (file)
--- 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