Em Tue, 18 Feb 2025 13:59:10 -0700 Jonathan Corbet <corbet@xxxxxxx> escreveu: > Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
