From 3f34478007a2423399dbdfae5e3deeca3898da9c Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 14 Aug 2025 18:13:16 +0100 Subject: docs/sphinx/kerneldoc.py: Handle new LINENO syntax The new upstream kernel-doc that we plan to update to uses a different syntax for the LINENO directives that the Sphinx extension parses: instead of #define LINENO 86 it has .. LINENO 86 Update the kerneldoc.py extension to handle both syntaxes, so that it will work with both the old and the new kernel-doc. Signed-off-by: Peter Maydell Reviewed-by: Paolo Bonzini Reviewed-by: Mauro Carvalho Chehab Message-id: 20250814171324.1614516-2-peter.maydell@linaro.org --- docs/sphinx/kerneldoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/sphinx/kerneldoc.py') diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py index 3aa972f2e8..30bb343198 100644 --- a/docs/sphinx/kerneldoc.py +++ b/docs/sphinx/kerneldoc.py @@ -127,7 +127,7 @@ class KernelDocDirective(Directive): result = ViewList() lineoffset = 0; - line_regex = re.compile("^#define LINENO ([0-9]+)$") + line_regex = re.compile(r"^(?:\.\.|#define) LINENO ([0-9]+)$") for line in lines: match = line_regex.search(line) if match: -- cgit 1.4.1 From 33be8171e2fe02173d24ffd61bd97bf9c2b37834 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 14 Aug 2025 18:13:21 +0100 Subject: scripts/kerneldoc: Switch to the Python kernel-doc script Change the Sphinx config to run the new Python kernel-doc script instead of the Perl one. The only difference between the two is that the new script does not handle the -sphinx-version option, instead assuming that Sphinx is always at least version 3: so we must delete the code that passes that option to avoid the Python script complaining about an unknown option. QEMU's minimum Sphinx version is already 3.4.3, so this doesn't change the set of versions we can handle. Signed-off-by: Peter Maydell Reviewed-by: Paolo Bonzini Reviewed-by: Mauro Carvalho Chehab Message-id: 20250814171324.1614516-7-peter.maydell@linaro.org --- docs/conf.py | 4 +++- docs/sphinx/kerneldoc.py | 5 ----- 2 files changed, 3 insertions(+), 6 deletions(-) (limited to 'docs/sphinx/kerneldoc.py') diff --git a/docs/conf.py b/docs/conf.py index f892a6e1da..e09769e5f8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -341,7 +341,9 @@ man_make_section_directory = False # We use paths starting from qemu_docdir here so that you can run # sphinx-build from anywhere and the kerneldoc extension can still # find everything. -kerneldoc_bin = ['perl', os.path.join(qemu_docdir, '../scripts/kernel-doc')] +# Since kernel-doc is now a Python script, we should run it with whatever +# Python this sphinx is using (rather than letting it find one via env) +kerneldoc_bin = [sys.executable, os.path.join(qemu_docdir, '../scripts/kernel-doc.py')] kerneldoc_srctree = os.path.join(qemu_docdir, '..') hxtool_srctree = os.path.join(qemu_docdir, '..') qapidoc_srctree = os.path.join(qemu_docdir, '..') diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py index 30bb343198..9721072e47 100644 --- a/docs/sphinx/kerneldoc.py +++ b/docs/sphinx/kerneldoc.py @@ -63,11 +63,6 @@ class KernelDocDirective(Directive): env = self.state.document.settings.env cmd = env.config.kerneldoc_bin + ['-rst', '-enable-lineno'] - # Pass the version string to kernel-doc, as it needs to use a different - # dialect, depending what the C domain supports for each specific - # Sphinx versions - cmd += ['-sphinx-version', sphinx.__version__] - # Pass through the warnings-as-errors flag if env.config.kerneldoc_werror: cmd += ['-Werror'] -- cgit 1.4.1