[igt-dev] [PATCH i-g-t v2 1/1] scripts:igt-doc.py: add a parser to document tests inlined

[Mauro Carvalho Chehab]

On Mon, 13 Feb 2023 17:15:38 +0100
Kamil Konieczny <kamil.konieczny at linux.intel.com> wrote:

> Hi Mauro,
> 
> On 2023-02-09 at 12:57:12 +0100, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab at kernel.org>
> > 
> > Tests need to be documentation, as otherwise its goal will be
> > lost with time. Keeping documentation out of the sources is also
> > not such a good idea, as they tend to bitrot.
> > 
> > So, add a script to allow keeping the documentation inlined, and
> > add tools to verify if the documentation has gaps.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab at kernel.org>
> > ---
> >  scripts/igt_doc.py | 487 +++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 487 insertions(+)
> >  create mode 100755 scripts/igt_doc.py
> > 
> > diff --git a/scripts/igt_doc.py b/scripts/igt_doc.py
> > new file mode 100755
> > index 000000000000..292d99c1ef92
> > --- /dev/null
> > +++ b/scripts/igt_doc.py
> > @@ -0,0 +1,487 @@
> > +#!/usr/bin/env python3
> > +# pylint: disable=C0301,R0914,R0912,R0915
> > +# SPDX-License-Identifier: GPL-2.0  
> ----------------------------- ^
> This should be MIT

I'll then dual-license it with "(GPL-2.0 OR MIT)". I prefer keeping it
also being licensed as GPL, just in case we might end needing it
somewhere else.

> > +
> > +## Copyright (C) 2023    Intel Corporation                 ##
> > +## Author: Mauro Carvalho Chehab <mchehab at kernel.org>      ##
> > +##                                                         ##
> > +## Allow keeping inlined test documentation and validate   ##
> > +## if the documentation is kept updated.                   ##
> > +
> > +"""Maintain test plan and test implementation documentation on IGT."""
> > +
> > +import argparse
> > +import fileinput
> > +import re
> > +import subprocess
> > +import sys
> > +
> > +IGT_BUILD_PATH = 'build/'
> > +IGT_RUNNER = '/runner/igt_runner'
> > +
> > +# Fields that mat be inside TEST and SUBTEST macros
> > +fields = [
> > +    'Category',       # Hardware building block / Software building block / ...
> > +    'Sub-category',   # waitfence / dmabuf/ sysfs / debugfs / ...
> > +    'Coverered functionality', # basic test / ...  
> ------------^^
> Covered

I'll just place "Functionality".

> 
> > +    'Test type',      # functionality test / pereformance / stress  
> -------------------------------------------------- ^
> performance
> 
> > +    'Run type',       # BAT / workarouds / stress / developer-specific / ...  
> ------------------------------------------------------ ^
> I am not sure what is it.

I'll drop "developer-specific".

> 
> +cc Petri
> 
> Regards,
> Kamil