[igt-dev] [PATCH i-g-t 0/1] Add a script to document IGT tests

[Kamil Konieczny]

Hi Mauro,

I have one nit, please send such patches as a series with
second HAX, that HAX should delete and stop any testing in
our CI.

Regards,
Kamil

+cc Petri Latvala <adrinael at adrinael.net>
+cc Mauro Carvalho Chehab <mauro.chehab at linux.intel.com>

On 2023-02-03 at 09:26:49 +0100, Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab at kernel.org>
> 
> As the IGT and driver's code evolves, the meaning of the tests may
> become unclear. The best way to avoid bitrot is to have in-code
> documentation explaining what each test and subtest does.
> 
> This script adds support for in-code documentation placed on
> a style similar to kernel-doc, e. g. it should parse test descriptions
> like:
> 
> /**
>  * TEST: Check if new IGT test documentation logic functionality is working
>  * Category: Software build block
>  * Sub-category: documentation
>  * Coverered functionality: test documentation
>  * Test type: ReST generation
>  * Run type: IGT kunit test
>  * Issue: none
>  * Platforms: all
>  * Platform requirements: none
>  * Depends on: @igt at deadbeef@basic
>  * Requirements: Need at least a script to test it
>  * Description: Complete description of this test
>  *
>  * SUBTEST: foo
>  * Description: do foo things
>  * 	with description continuing on another line
>  *
>  * SUBTEST: bar
>  * Description: do bar things
>  * 	with description continuing on another line
>  */
> 
> /**
>  * SUBTEST: test-%s-binds-%s-with-%ld-size
>  * Description: Test arg[2] arg[1] binds with arg[3] size
>  *
>  * arg[1]:
>  *
>  * @large:	large
>  * 		something
>  * @mixed:	mixed
>  * 		something
>  * @small:	small
>  * 		something
>  *
>  * arg[2]:
>  *
>  * @binds:			foo
>  * @misaligned-binds:		misaligned
>  * @userptr-binds:		userptr
>  * @userptr-misaligned-binds:	userptr misaligned
>  *
>  * arg[3]:	buffer size
>  * 		in Kb
>  */
> 
> Please notice that I'm sending this script in advance, in order to
> have some upstream review. Such script currently is capable of
> describing igt tests and IGT subtests, with wildcard support.
> 
> It is not currently prepared to handle dynamic subtests, nor to
> describe Kernel selftest/KUnit. For those, it is probably worth
> to have the documentation inside the Kernel, to keep them as close
> as possible to the actual code.
> 
> The end goal is to use such script to describe the test bench for
> the new Xe driver, auto-generating documentation. The Xe IGT upstream
> work can be seen at https://patchwork.freedesktop.org/series/112191/.
> 
> Mauro Carvalho Chehab (1):
>   scripts: add a parser to produce documentation from Kernel C file
>     metatags
> 
>  scripts/igt-doc | 647 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 647 insertions(+)
>  create mode 100755 scripts/igt-doc
> 
> -- 
> 2.39.0
>