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

[Quentin Schulz]

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 <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
> 
> 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?

>             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

Cheers,
Quentin