Hi Peter,

This changeset does a new sync on the top of the Linux Kernel
kernel-doc changes. It is in sync with latest -next, plus
two series I submitted today to linux-doc:

- https://lore.kernel.org/linux-doc/cover.1769673038.git.mchehab+huawei@kernel.org/T/#t
- https://lore.kernel.org/linux-doc/cover.1769701598.git.mchehab+huawei@kernel.org/T/#t

After linux-doc picks my changes and this patch being applied
on QEMU, all differences between QEMU and the Linux Kernel
version will be only at scripts/kernel-doc.py.

With that, syncing from Linux kernel should be as simple as:

	cp <linux_dir>/docs/tools/lib/python/kdoc/*.py scripts/lib/kdoc/

and eventually add any new *.py file that it is there, if any.

The way this changeset works is that, at QEMU's kernel-doc.py
we have two new classes that are derivated from the kernel-doc
ones:

1. class QemuCTransforms(base class: CTransforms).

   The CTransforms class contains Linux-kernel function transform logic.
   all we need for QEMU is to add a new element to one of its lists:

	self.function_xforms += [
            # Add a handler for QEMU macros
            (KernRe(r"QEMU_[A-Z_]+ +"), ""),
        ]

2. class QemuRestFormat(base class: RestFormat):

   The RestFormat class contains the rules to output docs in rest
   format.

   All we need is to override self.highlights for it to use
   the QEMU way to define cross-references, e.g.:
	"#foo", instead of "&foo".

-

That's said, the newest kernel-doc version that this change is
using has gained support for documenting variables as well.

It could make sense to use it to document some global variables
where needed. The CTransforms as one list to do variable transforms
as well, so it could be used to document QEMU specific ways to
define static and extern vars.

Regards,
Mauro

Mauro Carvalho Chehab (1):
  scripts: Import Python kerneldoc from Linux kernel

 scripts/kernel-doc.py                  | 177 +++++++--
 scripts/lib/kdoc/__init__.py           |   0
 scripts/lib/kdoc/enrich_formatter.py   |  80 ++++
 scripts/lib/kdoc/kdoc_files.py         |  37 +-
 scripts/lib/kdoc/kdoc_item.py          |  18 +
 scripts/lib/kdoc/kdoc_output.py        | 120 ++++--
 scripts/lib/kdoc/kdoc_parser.py        | 432 +++++++++++----------
 scripts/lib/kdoc/kdoc_re.py            | 231 +++++++++---
 scripts/lib/kdoc/latex_fonts.py        | 184 +++++++++
 scripts/lib/kdoc/parse_data_structs.py | 498 +++++++++++++++++++++++++
 scripts/lib/kdoc/python_version.py     | 190 ++++++++++
 scripts/lib/kdoc/xforms_lists.py       | 105 ++++++
 12 files changed, 1711 insertions(+), 361 deletions(-)
 create mode 100644 scripts/lib/kdoc/__init__.py
 create mode 100644 scripts/lib/kdoc/enrich_formatter.py
 create mode 100755 scripts/lib/kdoc/latex_fonts.py
 create mode 100755 scripts/lib/kdoc/parse_data_structs.py
 create mode 100644 scripts/lib/kdoc/python_version.py
 create mode 100644 scripts/lib/kdoc/xforms_lists.py

-- 
2.52.0

On Thu, 29 Jan 2026 at 16:04, Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Hi Peter,
>
> This changeset does a new sync on the top of the Linux Kernel
> kernel-doc changes. It is in sync with latest -next, plus
> two series I submitted today to linux-doc:
>
> - https://lore.kernel.org/linux-doc/cover.1769673038.git.mchehab+huawei@kernel.org/T/#t
> - https://lore.kernel.org/linux-doc/cover.1769701598.git.mchehab+huawei@kernel.org/T/#t
>
> After linux-doc picks my changes and this patch being applied
> on QEMU, all differences between QEMU and the Linux Kernel
> version will be only at scripts/kernel-doc.py.
>
> With that, syncing from Linux kernel should be as simple as:
>
>         cp <linux_dir>/docs/tools/lib/python/kdoc/*.py scripts/lib/kdoc/
>
> and eventually add any new *.py file that it is there, if any.

This sounds great -- keeping the sync as simple as possible
is definitely what we want.

If you could ping me and/or respin the series once the changes
have landed in the kernel mainline, I'll pick them up for QEMU.

thanks
-- PMM

On Fri, 6 Feb 2026 15:04:27 +0000
Peter Maydell <peter.maydell@linaro.org> wrote:

> On Thu, 29 Jan 2026 at 16:04, Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > Hi Peter,
> >
> > This changeset does a new sync on the top of the Linux Kernel
> > kernel-doc changes. It is in sync with latest -next, plus
> > two series I submitted today to linux-doc:
> >
> > - https://lore.kernel.org/linux-doc/cover.1769673038.git.mchehab+huawei@kernel.org/T/#t
> > - https://lore.kernel.org/linux-doc/cover.1769701598.git.mchehab+huawei@kernel.org/T/#t
> >
> > After linux-doc picks my changes and this patch being applied
> > on QEMU, all differences between QEMU and the Linux Kernel
> > version will be only at scripts/kernel-doc.py.
> >
> > With that, syncing from Linux kernel should be as simple as:
> >
> >         cp <linux_dir>/docs/tools/lib/python/kdoc/*.py scripts/lib/kdoc/
> >
> > and eventually add any new *.py file that it is there, if any.  
> 
> This sounds great -- keeping the sync as simple as possible
> is definitely what we want.
> 
> If you could ping me and/or respin the series once the changes
> have landed in the kernel mainline, I'll pick them up for QEMU.

Sure! I will respin it once it reaches mainline (which should
be just cp the latest version).

-- 
Thanks,
Mauro