Re: [PATCH 0/1] Sync kernel-doc.py with Linux upstream

["Daniel P. Berrangé" <berrange@redhat.com>]

On Tue, Jan 13, 2026 at 11:44:51AM +0000, Peter Maydell wrote:
> On Tue, 6 Jan 2026 at 16:38, Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Hi Peter/John,
> >
> > There were several updates at kernel-doc upstream fixing bugs,
> > doing cleanups and a couple of improvements.
> >
> > Better to keep QEMU in sync with such changes.
> >
> > Worth mentioning that we did some changes on Linux at the
> > kernel-doc.py script itself, to avoid Kernel build to crash
> > with too old Python versions, as there docs build is a
> > separate target, and python >= 3.6 is a new requirement
> > there.
> >
> > On kernel, if python < 3.6, it will simply ignore docs
> > build (emitting a warning).
> >
> > I opted to not backport such changes, but if you prefer
> > doing that, I can do that on a v2.
> > ---
> >
> > For now, I opted to keep kernel-doc libraries at the same
> > directory as before - e.g. at scripts/lib/kdoc. On Linux,
> > we ended moving it to tools/lib/python/kdoc. It could make
> > sense to move it on QEMU too, as it makes a little bit
> > easier to keep things in sync.
> >
> > What do you think?
> 
> Hi; thanks for doing this backport. I checked that the output
> with this patch applied is still the same as with the old
> kernel-doc, and eyeballed the diffs between our kernel-doc
> and the Linux version, to confirm that we have kept our two
> minor QEMU-specific modifications and haven't missed anything
> from Linux's version that we ought to have. So:
> 
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> 
> On your two questions:
> 
> (1) As Dan says, QEMU already enforces a new enough
> Python version, so we don't need to handle 3.6. I think
> the main thing driving a choice to backport or not those
> changes would be simply keeping in sync with Linux's
> version of the script so we don't diverge. We want to
> make future re-syncing of the script as easy as possible.
> 
> (2) Regarding the location of the kernel-doc libraries:
> we seem to have two things here, possibly in tension:
>  - we don't want to gratuitously diverge from Linux
>  - QEMU's directory hierarchy is not the kernel's
> 
> In particular, I'm not sure tools/ is where we would
> naturally put python libraries used during the build
> process. Maybe that would be python/ for us, but I defer
> to John or another Python expert on that.

I tend to see the 'python' directory as being for stuff we formally
maintain as a python API for use by multiple internal consumers.

This is just a bunch of helper files exclusively for use by the kernel-doc
tool, and so the scripts/ directory is a decent fit for it, given that this
dir is for a collection of arbitary supporting tools & scripts.

As precedent, see the tracetool, which keeps all its helpers under
scripts/tracetool too.

TL;DR: I would not want to see a new top level tools/ directory
created, and don't think it fits in python/ either; scripts/ is
a fine home.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|