This RFC is a follow-up of the discussions taken here: https://lore.kernel.org/linux-doc/20230704132812.02ba97ba@maurocar-mobl2/T/#t
It adds a new extension that allows documenting tests using the same tool we're using for DRM unit tests at IGT GPU tools: https://gitlab.freedesktop.org/drm/igt-gpu-tools. While kernel-doc has provided documentation for in-lined functions/struct comments, it was not meant to document tests. Tests need to be grouped by the test functions. It should also be possible to produce other outputs from the documentation, to integrate it with test suites. For instance, Internally at Intel, we use the comments to generate DOT files hierarchically grouped per feature categories. This is just an initial RFC to start discussions around the solution. Before being merged upstream, we need to define what tags will be used to identify test markups and add a simple change at kernel-doc to let it ignore such markups. On this series, we have: - patch 1: adding test_list.py as present at the IGT tree, after a patch series to make it more generic: https://patchwork.freedesktop.org/series/120622/ - patch 2: adds an example about how tests could be documented. This is a really simple example, just to test the feature, specially designed to make easy to build just the test documentation from a single DRM kunit file. After discussions, my plan is to send a new version addressing the issues, and add some documentation for DRM and/or i915 kunit tests. Mauro Carvalho Chehab (2): docs: add support for documenting kUnit and kSelftests drm: add documentation for drm_buddy_test kUnit test Documentation/conf.py | 2 +- Documentation/index.rst | 2 +- Documentation/sphinx/test_kdoc.py | 108 ++ Documentation/sphinx/test_list.py | 1288 ++++++++++++++++++++++++ Documentation/tests/index.rst | 6 + Documentation/tests/kunit.rst | 5 + drivers/gpu/drm/tests/drm_buddy_test.c | 12 + 7 files changed, 1421 insertions(+), 2 deletions(-) create mode 100644 Documentation/sphinx/test_kdoc.py create mode 100644 Documentation/sphinx/test_list.py create mode 100644 Documentation/tests/index.rst create mode 100644 Documentation/tests/kunit.rst -- 2.40.1
