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

[Tom Rini]

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

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.

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

> 
> Cheers,
> Quentin

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20250512/4be59ed2/attachment.sig>