Re: [PATCH] scripts/kernel-doc: remove an obscure logic from kernel-doc

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue, 18 Feb 2025 13:59:10 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > With regards to the Python transition, since our Makefile allows
> > switching to a different script since ever[1], I'm playing with 
> > the idea of sending a patch series with:
> >
> > Patch 1: 
> >   - drops Sphinx version check from both kerneldoc 
> >     (-sphinx-version parameter) and the corresponding Sphinx extension;
> >
> > patch 2: 
> >   - renames kerneldoc to kerneldoc.pl
> >   - creates a symlink:
> > 	kerneldoc.pl -> kerneldoc
> >
> > patch 3:
> >   - adds kerneldoc.py:
> >
> > patch 4:
> >   - add info messages on both versions related to the transition,
> >     and instructions about using KERNELDOC=<script> makefile and ask
> >     people to report eventual regressions with new script.
> >
> > patch 5:
> >   - change kerneldoc symlink to point to kerneldoc.py
> >
> > We can then keep both for maybe one Kernel cycle and see how it goes,
> > stop accepting patches to the Perl version, in favor of doing the needed
> > changes at the Python one.
> >
> > If everything goes well, we can remove the venerable Perl version on the 
> > upcoming merge window, and change the Sphinx extension to use the Python
> > classes directly instead of running an external executable code.
> >
> > What do you think?  
> 
> Seems like a fine plan in general.  I wonder if we might want to keep
> the old kernel-doc a bit longer just in case, but we can decide that as
> we go.

Yeah, I'm unsure about keeping the old kernel-doc or not. Anyway, I'll
send a patch series without dropping the old kernel-doc script. 

We can remove it when we feel it is time for it.

> 
> > I'm in doubt if I should split the Kernel classes for the Python version
> > into a scripts/lib/kdoc directory on this series or doing such change
> > only after we drop the Perl version.
> >
> > Keeping it on a single file helps to do more complex code adjustments 
> > on a single place, specially if we end renaming/shifting stuff[2].  
> 
> Do whatever makes it easiest for you at this point, I'd say.

Ok, I'm opting to split it on multiple files, on separate patches. This
way, it is easier to review/compare the new script with the old one, in
case someone wants to do that.

For now, I opted to keep the two output classes (for rest and man output),
plus a base class used by both altogether. We may split it further in the
future, as needed.

With that, the final patchset will contain those files:

scripts/kernel-doc.py		- Command line tool
scripts/lib/kdoc/kdoc_re.py     - Regex ancillary classes
scripts/lib/kdoc/kdoc_parser.py - kernel-doc single file parser
scripts/lib/kdoc/kdoc_output.py - output classes
scripts/lib/kdoc/kdoc_files.py  - kernel-doc dispatcher for multiple 
				  files, providing a glue between the
				  parser and the output classes.

Please notice that the new tool can now parse multiple files at the
same time. For instance, if you want to generate a ReST file with
everything inside the Kernel tree, you could run:

	./scripts/kernel-doc.py .

(on my machine, this takes about 1 minute to run)

Such extra functionality is given by the class inside kdoc_files.py.

> > On a separate but related issue, perhaps we should start talking about
> > coding style. We don't have anything defined at the Kernel, and
> > different scripts follow different conventions (or most likely
> > don't follow any convention at all). We should probably think having 
> > something defined in the future.  
> 
> I've generally tried to stick to something that looks as close to the C
> coding style as possible.  Formalizing that might not be a bad idea at
> all.

Ok, I'll prepare something in the future to formalize a coding style.

For now, I'll add a .pylintrc file just to include the scripts/lib/*
directories we're currently using.

Thanks,
Mauro