[PATCH RFC] doc: Include pytests directly in documentation

[Tom Rini]

On Thu, Mar 06, 2025 at 05:03:02PM +0100, Heinrich Schuchardt wrote:
> On 25.02.25 21:50, Tom Rini wrote:
> > As there is support within the Sphinx framework to take Python
> > docstrings and generate documentation from it, we can make use of that
> > to more clearly and consistently document our pytests and how to
> > configure them. To do this we:
> > - Add PYTHONPATH to DOC_TARGETS so that modules will be found, have CI
> >    install pytest module as well.
> > - Add the autodoc extension for Python and then redirects so we can move
> >    py_testing.html (which is heavily referenced in archives, etc).
> > - Create a doc/develop/pytest directory and move the existing py_testing
> >    file there, update references.
> > - Update the test_000_version.py test to have a docstring
> > - Move the imports in test_net_boot.py so the docstring is in the
> >    correct place.
> > - Use code-block for all of the code blocks in test_net_boot.py so they
> >    are rendered correctly in documentation.
> >    - Adding these code-block lines makes the diff larger when read but a
> >      "git show -w" for example makes it clearer that the textual changes
> >      are removing '#' from lines so the output reads nicer.
> > 
> > Signed-off-by: Tom Rini <trini at konsulko.com>
> 
> Some of the test functions seem to lack documentation:
> 
> test_net_boot.setup_networking()
> test_net_boot.setup_tftpboot_boot()

Yes. Most of the tests need more documentation and only have a minimal
header comment.

> Would you know what 000 in the following filename corresponds to?
> 
> test/py/tests/test_000_version.py
> 
> Maybe we should rename to test_version.py it before adding this patch.

Yes, it's an ordering trick to ensure that we run this trivial test
first (and so can also fail out quickly). It should be documented.

> Tested-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
> Acked-by: Heinrich Schuchardt <xypron.glpk at gmx.de>

Thanks. I'll take that to mean you're conceptually fine with this so
I'll start on a real series that split the changes up and includes a
follow-up "now document this test better".

-- 
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/20250307/fd4ec827/attachment.sig>