[PATCH 0/1] Sync kernel-doc with newest upstrem changes

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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