Hi Tom,
On 5/12/25 4:07 PM, Tom Rini wrote:
On Mon, May 12, 2025 at 11:12:50AM +0200, Quentin Schulz wrote:
Hi Tom,
On 5/8/25 12:08 AM, Tom Rini wrote:
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 <tr...@konsulko.com>
---
Cc: Heinrich Schuchardt <xypron.g...@gmx.de>
Cc: Simon Glass <s...@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
Shouldn't we force a specific version of pytest like we would if it were
part of doc/sphinx/requirements.txt?
It's a good question. I don't know and I didn't want to drag the whole
of test/py/requirements.txt here nor have to worry about the pin in 2
places. I am hoping that for documentation needs this will be OK.
/me shrugs
Time will tell.
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
Can I recommend using a glob here to avoid having to constantly modify the
index.rst whenever a new file needs to be added to it?
.. toctree::
:maxdepth: 1
:glob:
test_*
for example, c.f.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-option-toctree-glob
Oh neat. Yes, that should be done instead. I wasn't expecting Heinrich
to pick it all up so quick, do you want to post a patch or should I do
it and Suggested-by you? Thanks!
Please go ahead with posting the patch :)
Thanks!
Quentin
