On Fri, 15 Aug 2025 at 10:39, Mauro Carvalho Chehab <mchehab+hua...@kernel.org> wrote: > > Hi Peter/Jonathan, > > Em Fri, 15 Aug 2025 10:11:09 +0100 > Jonathan Cameron <jonathan.came...@huawei.com> escreveu: > > > On Thu, 14 Aug 2025 18:13:15 +0100 > > Peter Maydell <peter.mayd...@linaro.org> wrote: > > > > > Earlier this year, the Linux kernel's kernel-doc script was rewritten > > > from the old Perl version into a shiny and hopefully more maintainable > > > Python version. This commit series updates our copy of this script > > > to the latest kernel version. I have tested it by comparing the > > > generated HTML documentation and checking that there are no > > > unexpected changes. > > Nice! Yeah, I had a branch here doing something similar for QEMU, > but got sidetracked by other things and didn't have time to address > a couple of issues. I'm glad you find the time for it. > > > > Luckily we are carrying very few local modifications to the Perl > > > script, so this is fairly straightforward. The structure of the > > > patchset is: > > > * a minor update to the kerneldoc.py Sphinx extension so it > > > will work with both old and new kernel-doc script output > > > * a fix to a doc comment markup error that I noticed while comparing > > > the HTML output from the two versions of the script > > > * import the new Python script, unmodified from the kernel's version > > > (conveniently the kernel calls it kernel-doc.py, so it doesn't > > > clash with the existing script) > > > > * make the changes to that library code that correspond to the > > > two local QEMU-specific changes we carry > > To make it easier to maintain and keep in sync with Kernel upstream, > perhaps we can try to change Kernel upstream to make easier for QEMU > to have a class override for the kdoc parser, allowing it to just > sync with Linux upstream, while having its own set of rules on a > separate file.
Mmm, this would certainly be nice, but at least so far we haven't needed to make extensive changes, luckily (you can see how small our local adjustments are here). > > > * tell sphinx to use the Python version > > > * delete the Perl script (I have put a diff of our local mods > > > to the Perl script in the commit message of this commit, for > > > posterity) > > > > > > The diffstat looks big, but almost all of it is "import the > > > kernel's new script that we trust and don't need to review in > > > detail" and "delete the old script". > > One thing that should be noticed is that Jonathan Corbet is currently > doing several cleanups at the Python script, simplifying some > regular expressions, avoiding them when str.replace() does the job > and adding comments. The end goal is to make it easier for developers > to understand and help maintaining its code. > > So, it is probably worth backporting Linux upstream changes after > the end of Kernel 6.17 cycle. Thanks for the heads-up on that one. A further sync should be straightforward after this one, I expect. > > > We should also update the Sphinx plugin itself (i.e. > > > docs/sphinx/kerneldoc.py), but because I did not need to do > > > that to update the main kernel-doc script, I have left that as > > > a separate todo item. > > The Kernel Sphinx plugin after the change is IMHO (*) a lot cleaner > than before, and hendles better kernel-doc warnings, as they are now > using Sphinx logger class. Also as much as anything else it's just nice for us not to diverge if we can avoid it. Incidentally, I'm curious if the kernel docs see problems with docutils 0.22 -- we had a report about problems there, at least some of which seem to be because the way kerneldoc.py adds its rST output is triggering the new docutils to complain if the added code doesn't have a consistent title style hierarchy: https://sourceforge.net/p/docutils/bugs/508/ (It looks like they're trying to address this on the docutils side; we might or might not adjust on our side too by fixing up the title styles if that's not too awkward for us.) > Btw, one important point to notice: if you picked the latest version > of kernel-doc, it currently requires at least Python 3.6 (3.7 is the > recommended minimal one). It does check that, silently bailing out > if Python < 3.6. QEMU already requires Python 3.9 or better; our configure checks: check_py_version() { # We require python >= 3.9. # NB: a True python conditional creates a non-zero return code (Failure) "$1" -c 'import sys; sys.exit(sys.version_info < (3,9))' } Thanks for the confirmation that the kernel is being more conservative on python requirements than we are; I did wonder about this but merely assumed you probably were rather than specifically checking :-) On this minor output change: > > > "Definition" sections now get output with a trailing colon: > > > > > > -<p><strong>Definition</strong></p> > > > +<div class="kernelindent docutils container"> > > > +<p><strong>Definition</strong>:</p> > > > > > > This seems like it might be a bug in kernel-doc since the Parameters, > > > Return, etc sections don't get the trailing colon. I don't think it's > > > important enough to worry about. is the extra colon intentional, or do you agree that it's a bug? You can see it in the kernel docs output at e.g. https://docs.kernel.org/core-api/workqueue.html#c.workqueue_attrs where in the documentation of struct workqueue_attrs, "Definition:" gets a kernel but the corresponding "Members" and "Description" don't. (Also "Description" is out-dented there when it probably should not be, but that's separate.) thanks -- PMM
