[PATCH v2 2/4] doc: pytest: Framework for documenting tests and document test_000_version

[Simon Glass]

Hi Tom,

On Thu, 8 May 2025 at 00:11, Tom Rini <trini at konsulko.com> 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 <trini at konsulko.com>
> ---
> Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
> Cc: Simon Glass <sjg at 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

Thank you for doing this.

>
> 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
>            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
> diff --git a/doc/develop/pytest/test_000_version.rst b/doc/develop/pytest/test_000_version.rst
> new file mode 100644
> index 000000000000..09e9a361729b
> --- /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 b95ceae23465..63d392e956e0 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

in the order

> +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.43.0
>

Reviewed-by: Simon Glass <sjg at chromium.org>

Regards,
Simon