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. > 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. > 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. jon
