[igt-dev] [PATCH i-g-t 1/1] scripts: add a parser to produce documentation from Kernel C file metatags

[Jani Nikula]

On Fri, 03 Feb 2023, Mauro Carvalho Chehab <mauro.chehab at linux.intel.com> wrote:
> On Fri, 3 Feb 2023 12:16:27 +0200
> Petri Latvala <adrinael at adrinael.net> wrote:
>
>> On Fri, Feb 03, 2023 at 09:26:50AM +0100, Mauro Carvalho Chehab wrote:
>> > From: Mauro Carvalho Chehab <mchehab at kernel.org>
>> > 
>> > On a similar approach to Kernel's kernel-doc script, add a parser
>> > that will produce documentation from special-purpose documentation
>> > tags inside IGT tests.
>> > 
>> > Signed-off-by: Mauro Carvalho Chehab <mchehab at kernel.org>
>> > ---
>> >  scripts/igt-doc | 647 ++++++++++++++++++++++++++++++++++++++++++++++++
>> >  1 file changed, 647 insertions(+)
>> >  create mode 100755 scripts/igt-doc
>> > 
>> > diff --git a/scripts/igt-doc b/scripts/igt-doc
>> > new file mode 100755
>> > index 000000000000..3ed2be144e61
>> > --- /dev/null
>> > +++ b/scripts/igt-doc
>> > @@ -0,0 +1,647 @@
>> > +#!/usr/bin/env perl  
>> 
>> 
>> When you talked about this beforehand, you talked about using
>> Python. Does this need to be a perl script? I mean, it's from kernel,
>> I understand that, but I'll be completely unable to review perl code
>> myself =(
>
> No, I didn't talk about writing it in Python. There are a couple of
> reasons why I opted to use Perl:
>
> 1. kernel-doc script is in perl too. It probably makes sense to also
>    add support the Kernel itself for test-related tags, in order to be
>    able to document KUnit tests. By using the same language, it is 
>    easier to place automation there too;

I don't think kernel-doc the script is a good argument here. On the
contrary, it should be an example of what not to do. It only exists as a
perl script because of legacy, and nothing else.

> 2. We have already perl scripts inside IGT (see code_cov_parse_info);

Which you added, and nobody else has touched since. Just saying.

> 3. Perl APIs are *a lot* more stable than Python; scripts written
>    a long time ago still runs OK without changes. Python, on the other
>    hand, keeps deprecating their APIs or changing them on non-compatible
>    ways from time to time, requiring more maintainance efforts just due
>    to its API changes.
>
> 4. I believe that each programmer should pick its own poison, writing
>    stuff using the environments they're more comfortable with. 
>    I'm not a Python programmer. I can probably review and write basic
>    changes on it, but writing something new there, using dictionaries
>    on an optimized code [1] is something that it would require a lot
>    of time from my side.

The above holds if you're working alone in a silo. IGT is above all a
team effort, and you need to consider the overall productivity of the
team, and the team's ability to maintain the code. Who's going to step
up if you're not there to do it? Are they going to have to rewrite the
whole thing in some other language?

The kernel-doc script is not a good argument here, because it suffers
from the same thing. Most people just don't want to touch it. I had to
hack on it when the original Sphinx conversion was done, and I'm still
#3 contributor to kernel-doc, and I don't even know perl. It's just
baffling.


BR,
Jani.


>
> [1] this script takes 100ms to parse and convert a set of tags for all
>     Xe IGT tags into ReST. On the (few) attempts I did to write similar
>     scripts, Python performed a lot worse.
>
> Regards,
> Mauro

-- 
Jani Nikula, Intel Open Source Graphics Center