Re: [RFC v2 00/38] Improve ABI documentation generation
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2025-01-29 14:22:10
Also in:
bpf, linux-arm-kernel, linux-block, linux-doc, linux-f2fs-devel, linux-hardening, linux-iio, linux-media, linux-pm, linux-usb, linux-wireless, lkml, workflows
Subsystem:
the rest · Maintainer:
Linus Torvalds
Em Wed, 29 Jan 2025 02:45:18 +0100 Mauro Carvalho Chehab [off-list ref] escreveu:
quoted
I've only tested with current Sphinx, have you tried this with the more ancient versions we support?Not yet, but I double-checked at Sphinx documentation to be sure that I won't be using any newer methods: I just kept using the same Sphinx API as used by other extensions at the Kernel.
Just checked it with Python 3.6 and Sphinx 3.4 on Fedora 41 with:
sudo dnf install python3.6.x86_64
python3.6 -m venv Sphinx-3.4
pip install alabaster Sphinx==3.4.3 pyyaml
There were some issues related to problems with early f-string
support, as reported by Akira.
After applying the enclosed patch, it is now working fine. The only
drawback is here:
- print(f"Defined on file{'s'[:len(files) ^ 1]}:\t{", ".join(files)}")
+ print("Defined on file(s):\t" + ", ".join(files))
As I removed the file/files auto-plural logic depending on the files
array length. Not a big deal.
I'll double-check if there's no other diff between old/new version
and add the enclosed patch in the end.
Thanks,
Mauro
[PATCH] scripts/get_abi.py: make it backward-compatible with Python 3.6
Despite being introduced on Python 3.6, the original implementation
was too limited: it doesn't accept anything but the argument.
Even on python 3.10.12, support was still limited, as more complex
operations cause SyntaxError:
Exception occurred:
File ".../linux/Documentation/sphinx/kernel_abi.py", line 48, in <module>
from get_abi import AbiParser
File ".../linux/scripts/get_abi.py", line 525
msg += f"{part}\n{"-" * len(part)}\n\n"
^
SyntaxError: f-string: expecting '}'
Replace f-strings by normal string concatenation when it doesn't
work on Python 3.6.
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
diff --git a/scripts/get_abi.py b/scripts/get_abi.py
index 543bed397c8c..e6e94f721fff 100755
--- a/scripts/get_abi.py
+++ b/scripts/get_abi.py@@ -522,7 +522,7 @@ class AbiParser: if cur_part and cur_part != part: part = cur_part - msg += f"{part}\n{"-" * len(part)}\n\n" + msg += part + "\n"+ "-" * len(part) +"\n\n" msg += f".. _{key}:\n\n"
@@ -546,7 +546,7 @@ class AbiParser: msg += f"Defined on file :ref:`{base} <{ref[1]}>`\n\n" if wtype == "File": - msg += f"{names[0]}\n{"-" * len(names[0])}\n\n" + msg += names[0] +"\n" + "-" * len(names[0]) +"\n\n" desc = v.get("description") if not desc and wtype != "File":
@@ -570,7 +570,8 @@ class AbiParser: users = v.get("users") if users and users.strip(" \t\n"): - msg += f"Users:\n\t{users.strip("\n").replace('\n', '\n\t')}\n\n" + users = users.strip("\n").replace('\n', '\n\t') + msg += f"Users:\n\t{users}\n\n" ln = v.get("line_no", 1)
@@ -596,7 +597,9 @@ class AbiParser: elif len(lines) == 1: f.append(f"{fname}:{lines[0]}") else: - f.append(f"{fname} lines {", ".join(str(x) for x in lines)}") + m = fname + "lines " + m += ", ".join(str(x) for x in lines) + f.append(m) self.log.warning("%s is defined %d times: %s", what, len(f), "; ".join(f))
@@ -644,10 +647,11 @@ class AbiParser: if users: print(f"Users:\t\t\t{users}") - print(f"Defined on file{'s'[:len(files) ^ 1]}:\t{", ".join(files)}") + print("Defined on file(s):\t" + ", ".join(files)) if desc: - print(f"\n{desc.strip("\n")}\n") + desc = desc.strip("\n") + print(f"\n{desc}\n") if not found_keys: print(f"Regular expression /{expr}/ not found.")