[PATCH 0/2] Restore kernel-doc support for Python 3.6

[PATCH 0/2] Restore kernel-doc support for Python 3.6

[Mauro Carvalho Chehab]

Hi Jon,

While discussing patch v2 12/12 from your kdoc series, I realized
that kernel-doc command line should not crash with Python 3.6,
nor cause compilation breakages with older versions.

The problem mainly affect builds with CONFIG_DRM enabled, due to:

drivers/gpu/drm/Makefile:                PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \
drivers/gpu/drm/i915/Makefile:    cmd_checkdoc = PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none -Werror $<
include/drm/Makefile:           PYTHONDONTWRITEBYTECODE=1 $(KERNELDOC) -none $(if $(CONFIG_WERROR)$(CONFIG_DRM_WERROR),-Werror) $<; \

This small series prevent Kernel build breakages on such case,
and it is meant to be merged after your kdoc patches.

Patch 1 emits a warning wih Python 3.7 siilar to kdoc class,
but on an early stage. More importantly, it emits a warning
and exits the script for versions <= 3.6. 

We still need the kdoc warning, as it detect troubles when
calling kernel-doc as a class.

Patch 2 fix a backward-compatibility issue that otherwise
would require Python 3.9.

With that, building the Kernel with older versions won't break.

Regards,
Mauro

Mauro Carvalho Chehab (2):
  docs: kernel-doc: emit warnings for ancient versions of Python
  scripts: kdoc: make it backward-compatible with Python 3.7

 scripts/kernel-doc.py           | 10 ++++++++++
 scripts/lib/kdoc/kdoc_parser.py |  4 +++-
 2 files changed, 13 insertions(+), 1 deletion(-)

-- 
2.50.0

[PATCH 1/2] docs: kernel-doc: emit warnings for ancient versions of Python

[Mauro Carvalho Chehab]

Kernel-doc requires at least version 3.6 to run, as it uses f-string.
Yet, Kernel build currently calls kernel-doc with -none on some places.
Better not to bail out when older versions are found.

Versions of Python prior to 3.7 do not guarantee to remember the insertion
order of dicts; since kernel-doc depends on that guarantee, running with
such older versions could result in output with reordered sections.

Check Python version when called via command line.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/kernel-doc.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index 12ae66f40bd7..fc3d46ef519f 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -271,6 +271,16 @@ def main():
 
     logger.addHandler(handler)
 
+    python_ver = sys.version_info[:2]
+    if python_ver < (3,6):
+        logger.warning("Python 3.6 or later is required by kernel-doc")
+
+        # Return 0 here to avoid breaking compilation
+        sys.exit(0)
+
+    if python_ver < (3,7):
+        logger.warning("Python 3.7 or later is required for correct results")
+
     if args.man:
         out_style = ManFormat(modulename=args.modulename)
     elif args.none:
-- 
2.50.0

Re: [PATCH 1/2] docs: kernel-doc: emit warnings for ancient versions of Python

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Kernel-doc requires at least version 3.6 to run, as it uses f-string.
> Yet, Kernel build currently calls kernel-doc with -none on some places.
> Better not to bail out when older versions are found.
>
> Versions of Python prior to 3.7 do not guarantee to remember the insertion
> order of dicts; since kernel-doc depends on that guarantee, running with
> such older versions could result in output with reordered sections.
>
> Check Python version when called via command line.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  scripts/kernel-doc.py | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
> index 12ae66f40bd7..fc3d46ef519f 100755
> --- a/scripts/kernel-doc.py
> +++ b/scripts/kernel-doc.py
> @@ -271,6 +271,16 @@ def main():
>  
>      logger.addHandler(handler)
>  
> +    python_ver = sys.version_info[:2]
> +    if python_ver < (3,6):
> +        logger.warning("Python 3.6 or later is required by kernel-doc")

Does this really work on truly old Python versions?  I don't have an
easy way to try it, but I would expect things to fail with a syntax
error (due to the f-strings) at the import stage...?

Thanks,

jon

[PATCH 2/2] scripts: kdoc: make it backward-compatible with Python 3.7

[Mauro Carvalho Chehab]

There was a change at kdoc that ended breaking compatibility
with Python 3.7: str.removesuffix() was introduced on version
3.9.

Restore backward compatibility.

Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/57be9f77-9a94-4cde-aacb-184cae111506@gmail.com/
Fixes: 27ad33b6b349 ("kernel-doc: Fix symbol matching for dropped suffixes")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/lib/kdoc/kdoc_parser.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 831f061f61b8..6273141033a8 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1214,7 +1214,9 @@ class KernelDoc:
         # Found an export, trim out any special suffixes
         #
         for suffix in suffixes:
-            symbol = symbol.removesuffix(suffix)
+            # Be backward compatible with Python < 3.9
+            if symbol.endswith(suffix):
+                symbol = symbol[:-len(suffix)]
         function_set.add(symbol)
         return True
 
-- 
2.50.0