From nobody Tue Oct 7 08:32:09 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