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. > > > 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
signature.asc
Description: PGP signature
