While we do need at least 3.6 for kernel-doc to work, and at least
3.7 for it to output functions and structs with parameters at the
right order, let the python binary be compatible with legacy
versions.
The rationale is that the Kernel build nowadays calls kernel-doc
with -none on some places. Better not to bail out when older
versions are found.
With that, potentially this will run with python 2.7 and 3.2+,
according with vermin:
$ vermin --no-tips -v ./scripts/kernel-doc
Detecting python files..
Analyzing using 24 processes..
2.7, 3.2 /new_devel/v4l/docs/scripts/kernel-doc
Minimum required versions: 2.7, 3.2
I actually tested it with versions 2.7 and 3.4 using anaconda
(version 3 < 3.4 was not available there). For both, the
script didn't crash and emitted the right warning:
$ conda create -n py27 python=2.7
$ conda activate py27
$ python ./scripts/kernel-doc --none include/media
Error: Python 3.6 or later is required by kernel-doc
$ conda deactivate
$ conda create -n py34 python=3.4
$ conda activate py34
python --version
Python 3.4.5
$ python ./scripts/kernel-doc --none include/media
Error: Python 3.6 or later is required by kernel-doc
$ conda deactivate
$ python --version
Python 3.13.5
$ python ./scripts/kernel-doc --none include/media
(no warnings and script ran properly)
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
scripts/kernel-doc.py | 37 ++++++++++++++++++++++++++-----------
1 file changed, 26 insertions(+), 11 deletions(-)
diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py
index fc3d46ef519f..d4f9188d6a19 100755
--- a/scripts/kernel-doc.py
+++ b/scripts/kernel-doc.py
@@ -1,9 +1,19 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
# SPDX-License-Identifier: GPL-2.0
# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>.
#
-# pylint: disable=C0103,R0915
-#
+# pylint: disable=C0103,R0912,R0914,R0915
+
+# NOTE: While kernel-doc requires at least version 3.6 to run, the
+# command line explicitly supports Python 2,7 and 3.4+.
+# The rationale is that it shall fail gracefully during Kernel
+# compilation with older Kernel versions. Due to that:
+# - encoding line is needed here;
+# - no f-strings can be used on this file.
+# - the libraries that require newer versions can only be included
+# after Python version is checked.
+
# Converted from the kernel-doc script originally written in Perl
# under GPLv2, copyrighted since 1998 by the following authors:
#
@@ -107,9 +117,6 @@ SRC_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
-from kdoc_files import KernelFiles # pylint: disable=C0413
-from kdoc_output import RestFormat, ManFormat # pylint: disable=C0413
-
DESC = """
Read C language source or header FILEs, extract embedded documentation comments,
and print formatted documentation to standard output.
@@ -273,14 +280,22 @@ def main():
python_ver = sys.version_info[:2]
if python_ver < (3,6):
- logger.warning("Python 3.6 or later is required by kernel-doc")
+ # Depending on Kernel configuration, kernel-doc --none is called at
+ # build time. As we don't want to break compilation due to the
+ # usage of an old Python version, return 0 here.
+ if args.none:
+ logger.error("Python 3.6 or later is required by kernel-doc. skipping checks")
+ sys.exit(0)
- # Return 0 here to avoid breaking compilation
- sys.exit(0)
+ sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
if python_ver < (3,7):
logger.warning("Python 3.7 or later is required for correct results")
+ # Import kernel-doc libraries only after checking Python version
+ from kdoc_files import KernelFiles # pylint: disable=C0415
+ from kdoc_output import RestFormat, ManFormat # pylint: disable=C0415
+
if args.man:
out_style = ManFormat(modulename=args.modulename)
elif args.none:
@@ -308,11 +323,11 @@ def main():
sys.exit(0)
if args.werror:
- print(f"{error_count} warnings as errors")
+ print("%s warnings as errors" % error_count) # pylint: disable=C0209
sys.exit(error_count)
if args.verbose:
- print(f"{error_count} errors")
+ print("%s errors" % error_count) # pylint: disable=C0209
if args.none:
sys.exit(0)
--
2.49.0
