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

[Quentin Schulz]

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

/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