From nobody Tue Oct 7 06:50:06 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C523E254848; Sat, 12 Jul 2025 08:13:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752308034; cv=none; b=MOw4YrDSo5aRiU9vw7lN69L4G3bWVy3gVxaxcUDegzUSRgC3nH+agnEcQWeKLobUg0sTXjDZncKhOD+X2oGw0QhV8tkG2vfUI9weJO/3fnpiId8RtLAKUc6ViH1yaSu+gA+5xFQnY109AwZkSNOkTzcJfBICA0HN0M22G9eERm8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752308034; c=relaxed/simple; bh=ua5PApvy1DPn+jaoFt7I+58zAD2EcQFSm7ku/DyCCMc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=lJ9w9rVHCjVmm+JNWeezTCs6BUZz4x//1+uTY6Pa50pDIBlphfBrEhTjucEgxUGPtlEL+KatONAyHASIBp7tP64j+g0/anNBZhuuIPbAopznSQTv1pEwpvj5T287BdOMipgJXDMtFOAixPEbdAevR4SgOahtNv99Yx02qvEJf5s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Fu4PIXE0; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Fu4PIXE0" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3D189C4CEF5; Sat, 12 Jul 2025 08:13:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1752308034; bh=ua5PApvy1DPn+jaoFt7I+58zAD2EcQFSm7ku/DyCCMc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Fu4PIXE0Uh+JC0FJ5Srz+r4Rb2K9g/xcbCAbqSBnh4wKFWHlX89gddFKI9zONTL9+ 8acWnNit8xsCVre/e0Xa6eJmTVFrYbTZKihm+xjCUPVJGQnZtXFQ5KemMJHOLJ4IyN 3PoFnPoaEsDYBltG3T2e26DzqWoSWFxNoy/2NblRB+xrvDUGQeSWprlZRh2GiMxu4M ETHI5M8DIkmiuQULjhK8rt7woZ3oRSWGNhJP04gRnhj+ScM3YNPa80ihYGy3dj30ez tgFXJD5qHiSiaX4UxI0fXACW2iWpmXBW6eNlc7xvUj2M7NEjflR9Xx8zCpDVJi+l/o OdYRihvNXLHoA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uaVMm-0000000GrLu-11DO; Sat, 12 Jul 2025 10:13:52 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v2 1/2] docs: kernel-doc: emit warnings for ancient versions of Python Date: Sat, 12 Jul 2025 10:13:43 +0200 Message-ID: <38c42f000ad7f33c2b988f487678ddc085226221.1752307866.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.50.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" 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 and ensure that it will run with a much older version, failing after checking arguments, but return 0 to avoid breaking Kernel compilation. 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 tested myself with versions 2.7 and 3.4 using anaconda (version 3 < 3.4 is not available there) $ conda create -n py27 python=3D2.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=3D3.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 Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index 12ae66f40bd7..c59eea3e0fe9 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -1,9 +1,19 @@ #!/usr/bin/env python3 +# -*- coding: utf-8 -*- # SPDX-License-Identifier: GPL-2.0 # Copyright(c) 2025: Mauro Carvalho Chehab . # -# pylint: disable=3DC0103,R0915 -# +# pylint: disable=3DC0103,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 =3D os.path.dirname(os.path.realpath(__file__)) =20 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) =20 -from kdoc_files import KernelFiles # pylint: disable= =3DC0413 -from kdoc_output import RestFormat, ManFormat # pylint: disable= =3DC0413 - DESC =3D """ Read C language source or header FILEs, extract embedded documentation com= ments, and print formatted documentation to standard output. @@ -271,6 +278,20 @@ def main(): =20 logger.addHandler(handler) =20 + python_ver =3D sys.version_info[:2] + if python_ver < (3,6): + logger.error("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 result= s") + + # Import kernel-doc libraries only after checking Python version + from kdoc_files import KernelFiles # pylint: disable= =3DC0415 + from kdoc_output import RestFormat, ManFormat # pylint: disable= =3DC0415 + if args.man: out_style =3D ManFormat(modulename=3Dargs.modulename) elif args.none: @@ -298,11 +319,11 @@ def main(): sys.exit(0) =20 if args.werror: - print(f"{error_count} warnings as errors") + print("%s warnings as errors" % error_count) # pylint: disable= =3DC0209 sys.exit(error_count) =20 if args.verbose: - print(f"{error_count} errors") + print("%s errors" % error_count) # pylint: disable= =3DC0209 =20 if args.none: sys.exit(0) --=20 2.50.0 From nobody Tue Oct 7 06:50:06 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C52A025484A; Sat, 12 Jul 2025 08:13:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752308034; cv=none; b=c1YMHQu3uANHHVGdaMTJ4sOEifYq7rr27N3bSFZB6ZPnZWCMsDYCgzkh9p79jeOjVZNaZOKtjEJj+zZ3JOsyMpc00nUaTXcw4SQbtyPj1Pqi2eLG3udkhb3Aq+h2unAAS7yKcrh4lsOxTqiN1FhK8LpEmlrhe2ZtcZc1PWyQzTE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752308034; c=relaxed/simple; bh=nBkQTkDhZsnzFFW82qYBM0kzGOHtVEnCtN29bE/ppyI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=FNvIaw2XLE1/Y+oxD2Dc3n+XPhOe3StTndK+gQ6n5Wg8byUp2EQAtACv1QXJkw9XZf4SK1Lk7dmIH/2y3CV9WYHJKpSwQdFdxtmr1lIeY5YTwMQ8b7l4xHWUT0rwiaUFpzAXcB6aH7DzBFVJCpopcZMi7CbUn+/C6pW7SbpcdRk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ul/PmPWz; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ul/PmPWz" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3EFD0C4CEF7; Sat, 12 Jul 2025 08:13:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1752308034; bh=nBkQTkDhZsnzFFW82qYBM0kzGOHtVEnCtN29bE/ppyI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ul/PmPWzFaB3KkRMuVpcpdboqnOOAv0KQeyuSd01ZE/jqsZ3T7W4SA/KkLeg0wBGB i1J9NMNyScerZo2ASJs/lyPqHhqQDsFuyfb9bwgg8EVlgDjP3iDxVnSxzESQqtqtj0 HthylsFDK42tRBVSHEkXmkycGMZgT+cwtmZpYXhSwVHrLeJFjYdEvsV7/rKuc1J8U1 d95SK2EsCUmq+y2lv/goO08WZmzTCzto4iMVzKG8ICm2aWJmc+OXatsYUVUEfgjx0+ 0iymOqrMJbJbJy0jknVaPvH9WPikLCXAe8ggKkcLM6Gcn8KUhj5XeJxuChWcD94eE4 uMTJHcJdQKRvA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uaVMm-0000000GrLy-184g; Sat, 12 Jul 2025 10:13:52 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Matthew Wilcox (Oracle)" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v2 2/2] scripts: kdoc: make it backward-compatible with Python 3.7 Date: Sat, 12 Jul 2025 10:13:44 +0200 Message-ID: X-Mailer: git-send-email 2.50.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" 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 Closes: https://lore.kernel.org/linux-doc/57be9f77-9a94-4cde-aacb-184cae111= 506@gmail.com/ Fixes: 27ad33b6b349 ("kernel-doc: Fix symbol matching for dropped suffixes") Signed-off-by: Mauro Carvalho Chehab --- 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 =3D symbol.removesuffix(suffix) + # Be backward compatible with Python < 3.9 + if symbol.endswith(suffix): + symbol =3D symbol[:-len(suffix)] function_set.add(symbol) return True =20 --=20 2.50.0 From nobody Tue Oct 7 06:50:06 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DAD772FB2; Sat, 12 Jul 2025 08:33:37 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752309218; cv=none; b=d3Zoto/Nz5Pr/VlBE/g9ehSiHxNfT772qPHMAnJGPiwMJKfcI7pGGSFNVrVsgaR62d3X8jXdfrcVFcUtbRDEfihS9i1ITuvLp6WPStAlCgodOlEYBhRMeZ6tc//iJ+87KzYe6+rhmo5+YJ4yIrbPkkVNXxaLqdSAuuZoV3ow4CM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1752309218; c=relaxed/simple; bh=6VWw+bBtOU9U2/e33hN+xWFLVR6yatLAPxZzl7SbJNQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tVM7y7we2Qs/twPdAd/fH5CJwUVANzS8FIu8HbjyoRTrrIKDEhhi9/lb5YOgBB6Fz+9LmK4JWUsPpiwYYCZ4CVK6FIDOKydV1tH/MH9uIVI3l11PgfofB1jj2YXzqrY2/t7aYX9khuiH9UGvlBa9qjwQe6aejlnTvQLoOlgSCAw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=BLrBtGJW; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="BLrBtGJW" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 681C1C4CEEF; Sat, 12 Jul 2025 08:33:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1752309217; bh=6VWw+bBtOU9U2/e33hN+xWFLVR6yatLAPxZzl7SbJNQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BLrBtGJWr8t8EuUuF1KitSwtsdhjcVkm7yA3/9/v0SPnsfWTGsgArG0c37KqNC5FZ Z37V4hCTuE2wtvT5T+1lKkmEWide4h7GDLgNjmYmZGscJgAPABaYhvWKq8fs8dGG68 hCNpNVmeFhYdndohsRc8K1MDbvyXuxyd4JuN6z+QWhxVTH1EI9cKdCTeBPzViN+dy1 Wf7EhAxuECXW4VY00z2WWJtOB4yLLOH86VsdFfZZGEE2Kxjh72zulx41D1Ey5THtmp NRAuSk5U6nVqcUZ6FcbAX4k9NePoy4l0WMLB8nUrypDr0OqhZzWYcmYJ9EVs/Jbh0g y9zTO6eQRTGTQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uaVfr-0000000GsSz-1qLn; Sat, 12 Jul 2025 10:33:35 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org, workflows@vger.kernel.org, Akira Yokosawa Subject: [PATCH v2 3/2] docs: changes: better document Python needs Date: Sat, 12 Jul 2025 10:32:38 +0200 Message-ID: <58c0cfb40e600af697b1665ffbc8e5bb3d859bb5.1752309145.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.50.0 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Python is listed as an optional dependency, but this is not true, as kernel-doc is called during compilation when DRM is enabled. Better document that. Signed-off-by: Mauro Carvalho Chehab --- Documentation/process/changes.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/process/changes.rst b/Documentation/process/chan= ges.rst index bccfa19b45df..6a7d7c1ee274 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -61,7 +61,7 @@ Sphinx\ [#f1]_ 3.4.3 sphinx-build --ve= rsion GNU tar 1.28 tar --version gtags (optional) 6.6.5 gtags --version mkimage (optional) 2017.01 mkimage --version -Python (optional) 3.9.x python3 --version +Python 3.9.x python3 --version GNU AWK (optional) 5.1.0 gawk --version =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 @@ -154,6 +154,13 @@ Perl You will need perl 5 and the following modules: ``Getopt::Long``, ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kerne= l. =20 +Python +------ + +At least Python 2.7 or 3.4 is required if CONFIG_DRM is selected to avoid +breaking compilation. Documentation build and kernel-doc won't produce +valid results if version is below 3.7. + BC -- =20 --=20 2.50.0