From nobody Thu Oct 9 08:43:03 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 C35EA2BE7DA; Wed, 18 Jun 2025 11:46:51 +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=1750247211; cv=none; b=ANPQEgDZjWpCQ3I+/Jv0W/Xa5dl7Xn3+xqDN9t7w4Bh33xJ4sukboaP7CdU3DnOud4341yB0fpnVI8V+oauMcFFwIYAjRPNT4nBPei5/a1CkWOrQPpTDNYcDxUkYiRMoYH651VWzAyNZBEcm7NMbqcn0WbIyzsM2VzjVpza7QBI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247211; c=relaxed/simple; bh=JvTI+DF/1Dszyn4T0n7ZKhi6vNtj6FoC1Ae/TMd5FHM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=sjGsOZBabQXPpFJ9K8gH2xwf7lKjXlQTtlGnxhrtI2dJ3FZ7/W3Q0cku0XByICN0Z9XySlbo81B0bHG072mFEQEZ4Gslrs64lgNA255SlW0r/nexbEi1uXmT3Cv4YQa8BaYEhfds3DTmeMMgE06niWjUUE9orVWx2ebN7efQu2c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=lNpAhvIS; 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="lNpAhvIS" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 68E02C4AF09; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=JvTI+DF/1Dszyn4T0n7ZKhi6vNtj6FoC1Ae/TMd5FHM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lNpAhvIS8B9g/yY9cvaF5cSmS+QQVnN2qc8L9H7B8QbLCp0GCOynIFLNtIr8YkZkz mMMokwZpCg/5aa+JZcjZ4BcV1DmDMBHnodbIpEhnAYRKTUyDWjOyrw9Tq9FSVrR+va DtfpHGfhtruIEWDQvgPbUhsHYkS727pTZaLChdXMitYQML+M8T28pB0NFFo+7Im80I H8Rcs0D026838D5+6cIfG//c7jGhKj8893sYrj6PSZ+C+4EeBJN5+MqBLNjL3HlvKu mHPEy0bRBfAFb4hVZtWGrcLk/o/sliwm6p5a2TnKSpZdXFJBfWYCyMl/HRd7VWfFdv NpNIUbXMx5rsQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036UJ-1rob; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 01/15] docs: conf.py: properly handle include and exclude patterns Date: Wed, 18 Jun 2025 13:46:28 +0200 Message-ID: <737b08e891765dc10bd944d4d42f8b1e37b80275.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" When one does: make SPHINXDIRS=3D"foo" htmldocs All patterns would be relative to Documentation/foo, which causes the include/exclude patterns like: include_patterns =3D [ ... f'foo/*.{ext}', ] to break. This is not what it is expected. Address it by adding a logic to dynamically adjust the pattern when SPHINXDIRS is used. That allows adding parsers for other file types. It should be noticed that include_patterns was added on Sphinx 5.1: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-incl= ude_patterns So, a backward-compatible code is needed when we start using it for real. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Donald Hunter --- Documentation/conf.py | 67 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 12de52a2b17e..4ba4ee45e599 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -17,6 +17,66 @@ import os import sphinx import shutil =20 +# Get Sphinx version +major, minor, patch =3D sphinx.version_info[:3] + +# Include_patterns were added on Sphinx 5.1 +if (major < 5) or (major =3D=3D 5 and minor < 1): + has_include_patterns =3D False +else: + has_include_patterns =3D True + # Include patterns that don't contain directory names, in glob format + include_patterns =3D ['**.rst'] + +# Location of Documentation/ directory +doctree =3D os.path.abspath('.') + +# Exclude of patterns that don't contain directory names, in glob format. +exclude_patterns =3D [] + +# List of patterns that contain directory names in glob format. +dyn_include_patterns =3D [] +dyn_exclude_patterns =3D ['output'] + +# Properly handle include/exclude patterns +# ---------------------------------------- + +def update_patterns(app): + + """ + On Sphinx, all directories are relative to what it is passed as + SOURCEDIR parameter for sphinx-build. Due to that, all patterns + that have directory names on it need to be dynamically set, after + converting them to a relative patch. + + As Sphinx doesn't include any patterns outside SOURCEDIR, we should + exclude relative patterns that start with "../". + """ + + sourcedir =3D app.srcdir # full path to the source directory + builddir =3D os.environ.get("BUILDDIR") + + # setup include_patterns dynamically + if has_include_patterns: + for p in dyn_include_patterns: + full =3D os.path.join(doctree, p) + + rel_path =3D os.path.relpath(full, start =3D app.srcdir) + if rel_path.startswith("../"): + continue + + app.config.include_patterns.append(rel_path) + + # setup exclude_patterns dynamically + for p in dyn_exclude_patterns: + full =3D os.path.join(doctree, p) + + rel_path =3D os.path.relpath(full, start =3D app.srcdir) + if rel_path.startswith("../"): + continue + + app.config.exclude_patterns.append(rel_path) + # helper # ------ =20 @@ -219,10 +279,6 @@ language =3D 'en' # Else, today_fmt is used as the format for a strftime call. #today_fmt =3D '%B %d, %Y' =20 -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns =3D ['output'] - # The reST default role (used for this markup: `text`) to use for all # documents. #default_role =3D None @@ -516,3 +572,6 @@ kerneldoc_srctree =3D '..' # the last statement in the conf.py file # ------------------------------------------------------------------------= ------ loadConfig(globals()) + +def setup(app): + app.connect('builder-inited', update_patterns) --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 1080B2DBF4C; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=WIMbHWtkYz2XdfS7se/m6u9Vdn+XeqBl2X32SrBZPSlnG8vrhkPYNCan4iWucW8ptqLmC97VpDur9g7gmI7sPZYGINAbmDc1od9kxKXzSQNHwE03Lw1bdOcrJho2BIkLkaL5Kx66zPDhAdZ3SmEpVNY23De+696CowMFQvm5buE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=9sv3o8O8M0IyOR5wJkoSEusaPecRlQcEL5SoMo0iJ7A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=lw+jiwaF/Tfi2zyBRc3u6nRZXJEWzckD/zp5kF4ijgiMh64UdEMF/YzE/pkSquyU1OJkFjddPyh4j1Ss4NQK8unuptCK9x65I/kycFdsqH0j7Q1zP6ioIrSy2i+z0WxTb7vkeW227SygplSwnNGeelcRuOG5qbVR0rk27Ggfia4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=uKo5HGIf; 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="uKo5HGIf" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6B8B0C4AF0B; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=9sv3o8O8M0IyOR5wJkoSEusaPecRlQcEL5SoMo0iJ7A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uKo5HGIfommgZx8yi6Zi+eJ1SoQ2VQ+0T5muWeAbjZTUtGMXuu8g73Mc1KWSLPPCT RZSfdvSj+AetUWCOucjQtZDb/DrDX8D2GrPThxG0Nkjuvl7BM+ttN8nQyQfAGOrZpZ ZIk44uUGn5Ex2o6s1xNoHE2y0rYR8Bli8XYuPV/6XAnCbqZkoXc5ugdr2sRn4+05jp ob7sqMs3tDQDF8/X/sP7TUHE3diI7O/NbQCLZXz5ilJ+UejabNBc8zptGaFqjqJ6mK WCxOmyMFcUYh6vZrAkTiuyJ9gpmwhVe70bwe0v2CwmsXJHbyIy2QXlkevHf+jnaH2P R6+Uh2uam2B7w== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036UN-1zMZ; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 02/15] docs: Makefile: disable check rules on make cleandocs Date: Wed, 18 Jun 2025 13:46:29 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" It doesn't make sense to check for missing ABI and documents when cleaning the tree. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Breno Leitao Reviewed-by: Donald Hunter --- Documentation/Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/Makefile b/Documentation/Makefile index d30d66ddf1ad..b98477df5ddf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -5,6 +5,7 @@ # for cleaning subdir- :=3D devicetree/bindings =20 +ifneq ($(MAKECMDGOALS),cleandocs) # Check for broken documentation file references ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y) $(shell $(srctree)/scripts/documentation-file-ref-check --warn) @@ -14,6 +15,7 @@ endif ifeq ($(CONFIG_WARN_ABI_ERRORS),y) $(shell $(srctree)/scripts/get_abi.py --dir $(srctree)/Documentation/ABI v= alidate) endif +endif =20 # You can set these variables from the command line. SPHINXBUILD =3D sphinx-build --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 C4C972BEC28; Wed, 18 Jun 2025 11:46:51 +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=1750247211; cv=none; b=kkhK4sjKnPM546baCQzWSrbNxS1u/buw4QPaYRJKLoD3vLPAlKGMVyIjT8f97NgpZydebBZkixL1vfKt5UOFkNRKKvQ77USATSG2k1LqiF9lWPRLtnaDIiUMbaHeQKEBE9v0DKKzkROhbVBVgZmrgMPixpKX1H/yoyZcq5W9nEw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247211; c=relaxed/simple; bh=MZJWqI3Ttw/muYCtmcZ8ZV0+firnnb8VF0+QvKwQ1QU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Uioe4DoH9e3xAfV5CgbK02n93656xl5gFCzOhq5bO3imM5Ea5TiMu1jWl3titRd3+XXMOW7U60x2xBrcvoSzOsB7qIa75rF+AWxooQJ3waWoI6iNm9OrNLtTuYmbaQCSvLFwsoWmF0Qrr0Tgw/lTs6E8hmCclr2gArCUOljMcxE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=P91TIwux; 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="P91TIwux" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 59226C4CEE7; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=MZJWqI3Ttw/muYCtmcZ8ZV0+firnnb8VF0+QvKwQ1QU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=P91TIwuxhS2K9nDmQzM6kFxsLu9ADImckCvp9pDPV1AUX+4/xgi1rrQf5gmEhSjEm lQgkonVoIjkS60GRyPswnAJHSYa4fJguEgACI87M6Z8FhnoYzYYXugIrq7JDFsAicd wzNZIzZeueNuvcoZJRu2ncRFAOJVzu/M5i5kXEqpOvXi5FNg9w9HdLw/XxwynsplNk xXN2QOWBiqrcALkNK9qDPwFa6l+WUYeixXCM1LztaGoNslJFBxGmalCfGAWruUhLdW Q4LjPlImNUA7FLRFygbdYWMGGJbnSiuZkDn08F9R1anDFdbdBCW8dSiwuOQ+K7Fdnc Kl1CAAppMiDdQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036UR-26te; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 03/15] docs: netlink: netlink-raw.rst: use :ref: instead of :doc: Date: Wed, 18 Jun 2025 13:46:30 +0200 Message-ID: <205e2b0baddabf47ab23ed08fbddd3fdc0cdcc58.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Currently, rt documents are referred with: Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`rt-link<../../ne= tworking/netlink_spec/rt-link>` Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../network= ing/netlink_spec/tc>` Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../network= ing/netlink_spec/tc>` Having :doc: references with relative paths doesn't always work, as it may have troubles when O=3D is used. Also that's hard to maintain, and may break if we change the way rst files are generated from yaml. Better to use instead a reference for the netlink family. So, replace them by Sphinx cross-reference tag that are created by ynl_gen_rst.py. Signed-off-by: Mauro Carvalho Chehab --- Documentation/userspace-api/netlink/netlink-raw.rst | 6 +++--- tools/net/ynl/pyynl/ynl_gen_rst.py | 5 +++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Documentation/userspace-api/netlink/netlink-raw.rst b/Document= ation/userspace-api/netlink/netlink-raw.rst index 31fc91020eb3..aae296c170c5 100644 --- a/Documentation/userspace-api/netlink/netlink-raw.rst +++ b/Documentation/userspace-api/netlink/netlink-raw.rst @@ -62,8 +62,8 @@ Sub-messages ------------ =20 Several raw netlink families such as -:doc:`rt-link<../../networking/netlink_spec/rt-link>` and -:doc:`tc<../../networking/netlink_spec/tc>` use attribute nesting as an +:ref:`rt-link` and +:ref:`tc` use attribute nesting as an abstraction to carry module specific information. =20 Conceptually it looks as follows:: @@ -162,7 +162,7 @@ then this is an error. Nested struct definitions ------------------------- =20 -Many raw netlink families such as :doc:`tc<../../networking/netlink_spec/t= c>` +Many raw netlink families such as :ref:`tc` make use of nested struct definitions. The ``netlink-raw`` schema makes it possible to embed a struct within a struct definition using the ``struct`` property. For example, the following struct definition embeds the diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index 0cb6348e28d3..7bfb8ceeeefc 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -314,10 +314,11 @@ def parse_yaml(obj: Dict[str, Any]) -> str: =20 # Main header =20 - lines.append(rst_header()) - family =3D obj['name'] =20 + lines.append(rst_header()) + lines.append(rst_label("netlink-" + family)) + title =3D f"Family ``{family}`` netlink specification" lines.append(rst_title(title)) lines.append(rst_paragraph(".. contents:: :depth: 3\n")) --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 4B3B72DE214; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=dLnfrb2Jr9odlgM2+ffPCY/7MWVuFUFhlL1+dH/h3XuFZOk/AZ3fUizVhop/ffppVKTdPZY1/WNG4HQOB087nfAFx4FhMVhFwh+ZB0GO9w2SX7xm0PT82wHyrTCWcnNh7wCKJlnvPW1ejkF6IfnucFSoIJQo4CD6UbR6qPk7swg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=ILMkIMZRBVquHVA7G08AHG7My5iKhrMAj1qGVO2Pimg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=coVEZXz9JspznbW67CnHr7jqfRJ6mvFaojpEJAtx0cHf+aa8EnnrVQwwVpI8PIZoJi9fQzKGV4ezi7Cd7fY6RlqsA35u20OsDY1SDK30TW6wCVZluvPyZSumak6emLsMQFJlxqOVWOI/djIisY/+aXs8XFp1VLov9VBWL1JOY9s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sQ7blse+; 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="sQ7blse+" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 643EFC4CEF2; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=ILMkIMZRBVquHVA7G08AHG7My5iKhrMAj1qGVO2Pimg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sQ7blse+yZjDClmiXQlLiQIQDfEVRDh5w2t6ILU0woHepKIhtI4GHlj8fYAL+UALQ AV9IZEHnxWFfi7XMYqzDLKhRUQvUJN+VGKcq8JttfzDEETmtl4avNMderF7txSY6sR p1ir4BhJMYXrB0ncmSAsnFLP5wF4w4QPyuMw5qJtB5iemZCRRSaj84Tp5E5aqzqT3w m8IrgHlB0qGMTOZI2o/oavdSL4A0HlqhNJxuWRke/IpDbTHBAa7dl7NH/ZVWp3lVG2 oeTRiv0q2bBWuuOMoQp07/PNIo2qkMgf+7oN/Tacq0Lz+m89dM4MQw5c0wXO1Q+0FK wwXPLu/aHCZuw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036UW-2EYe; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 04/15] tools: ynl_gen_rst.py: Split library from command line tool Date: Wed, 18 Jun 2025 13:46:31 +0200 Message-ID: <4e26583ad1d8a05ba40cada4213c95120bd45efc.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" As we'll be using the Netlink specs parser inside a Sphinx extension, move the library part from the command line parser. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- tools/net/ynl/pyynl/lib/__init__.py | 2 + tools/net/ynl/pyynl/lib/doc_generator.py | 409 +++++++++++++++++++++++ tools/net/ynl/pyynl/ynl_gen_rst.py | 361 +------------------- 3 files changed, 419 insertions(+), 353 deletions(-) create mode 100644 tools/net/ynl/pyynl/lib/doc_generator.py diff --git a/tools/net/ynl/pyynl/lib/__init__.py b/tools/net/ynl/pyynl/lib/= __init__.py index 71518b9842ee..5f266ebe4526 100644 --- a/tools/net/ynl/pyynl/lib/__init__.py +++ b/tools/net/ynl/pyynl/lib/__init__.py @@ -4,6 +4,8 @@ from .nlspec import SpecAttr, SpecAttrSet, SpecEnumEntry, S= pecEnumSet, \ SpecFamily, SpecOperation, SpecSubMessage, SpecSubMessageFormat from .ynl import YnlFamily, Netlink, NlError =20 +from .doc_generator import YnlDocGenerator + __all__ =3D ["SpecAttr", "SpecAttrSet", "SpecEnumEntry", "SpecEnumSet", "SpecFamily", "SpecOperation", "SpecSubMessage", "SpecSubMessag= eFormat", "YnlFamily", "Netlink", "NlError"] diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl= /lib/doc_generator.py new file mode 100644 index 000000000000..839e78b39de3 --- /dev/null +++ b/tools/net/ynl/pyynl/lib/doc_generator.py @@ -0,0 +1,409 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# -*- coding: utf-8; mode: python -*- + +""" + Class to auto generate the documentation for Netlink specifications. + + :copyright: Copyright (C) 2023 Breno Leitao + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + This class performs extensive parsing to the Linux kernel's netlink YA= ML + spec files, in an effort to avoid needing to heavily mark up the origi= nal + YAML file. + + This code is split in two classes: + 1) RST formatters: Use to convert a string to a RST output + 2) YAML Netlink (YNL) doc generator: Generate docs from YAML data +""" + +from typing import Any, Dict, List +import os.path +import sys +import argparse +import logging +import yaml + + +# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +# RST Formatters +# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +class RstFormatters: + SPACE_PER_LEVEL =3D 4 + + @staticmethod + def headroom(level: int) -> str: + """Return space to format""" + return " " * (level * RstFormatters.SPACE_PER_LEVEL) + + + @staticmethod + def bold(text: str) -> str: + """Format bold text""" + return f"**{text}**" + + + @staticmethod + def inline(text: str) -> str: + """Format inline text""" + return f"``{text}``" + + + @staticmethod + def sanitize(text: str) -> str: + """Remove newlines and multiple spaces""" + # This is useful for some fields that are spread across multiple l= ines + return str(text).replace("\n", " ").strip() + + + def rst_fields(self, key: str, value: str, level: int =3D 0) -> str: + """Return a RST formatted field""" + return self.headroom(level) + f":{key}: {value}" + + + def rst_definition(self, key: str, value: Any, level: int =3D 0) -> st= r: + """Format a single rst definition""" + return self.headroom(level) + key + "\n" + self.headroom(level + 1= ) + str(value) + + + def rst_paragraph(self, paragraph: str, level: int =3D 0) -> str: + """Return a formatted paragraph""" + return self.headroom(level) + paragraph + + + def rst_bullet(self, item: str, level: int =3D 0) -> str: + """Return a formatted a bullet""" + return self.headroom(level) + f"- {item}" + + + @staticmethod + def rst_subsection(title: str) -> str: + """Add a sub-section to the document""" + return f"{title}\n" + "-" * len(title) + + + @staticmethod + def rst_subsubsection(title: str) -> str: + """Add a sub-sub-section to the document""" + return f"{title}\n" + "~" * len(title) + + + @staticmethod + def rst_section(namespace: str, prefix: str, title: str) -> str: + """Add a section to the document""" + return f".. _{namespace}-{prefix}-{title}:\n\n{title}\n" + "=3D" *= len(title) + + + @staticmethod + def rst_subtitle(title: str) -> str: + """Add a subtitle to the document""" + return "\n" + "-" * len(title) + f"\n{title}\n" + "-" * len(title)= + "\n\n" + + + @staticmethod + def rst_title(title: str) -> str: + """Add a title to the document""" + return "=3D" * len(title) + f"\n{title}\n" + "=3D" * len(title) + = "\n\n" + + + def rst_list_inline(self, list_: List[str], level: int =3D 0) -> str: + """Format a list using inlines""" + return self.headroom(level) + "[" + ", ".join(self.inline(i) for i= in list_) + "]" + + + @staticmethod + def rst_ref(namespace: str, prefix: str, name: str) -> str: + """Add a hyperlink to the document""" + mappings =3D {'enum': 'definition', + 'fixed-header': 'definition', + 'nested-attributes': 'attribute-set', + 'struct': 'definition'} + if prefix in mappings: + prefix =3D mappings[prefix] + return f":ref:`{namespace}-{prefix}-{name}`" + + + def rst_header(self) -> str: + """The headers for all the auto generated RST files""" + lines =3D [] + + lines.append(self.rst_paragraph(".. SPDX-License-Identifier: GPL-2= .0")) + lines.append(self.rst_paragraph(".. NOTE: This document was auto-g= enerated.\n\n")) + + return "\n".join(lines) + + + @staticmethod + def rst_toctree(maxdepth: int =3D 2) -> str: + """Generate a toctree RST primitive""" + lines =3D [] + + lines.append(".. toctree::") + lines.append(f" :maxdepth: {maxdepth}\n\n") + + return "\n".join(lines) + + + @staticmethod + def rst_label(title: str) -> str: + """Return a formatted label""" + return f".. _{title}:\n\n" + +# =3D=3D=3D=3D=3D=3D=3D +# Parsers +# =3D=3D=3D=3D=3D=3D=3D +class YnlDocGenerator: + + fmt =3D RstFormatters() + + def parse_mcast_group(self, mcast_group: List[Dict[str, Any]]) -> str: + """Parse 'multicast' group list and return a formatted string""" + lines =3D [] + for group in mcast_group: + lines.append(self.fmt.rst_bullet(group["name"])) + + return "\n".join(lines) + + + def parse_do(self, do_dict: Dict[str, Any], level: int =3D 0) -> str: + """Parse 'do' section and return a formatted string""" + lines =3D [] + for key in do_dict.keys(): + lines.append(self.fmt.rst_paragraph(self.fmt.bold(key), level = + 1)) + if key in ['request', 'reply']: + lines.append(self.parse_do_attributes(do_dict[key], level = + 1) + "\n") + else: + lines.append(self.fmt.headroom(level + 2) + do_dict[key] += "\n") + + return "\n".join(lines) + + + def parse_do_attributes(self, attrs: Dict[str, Any], level: int =3D 0)= -> str: + """Parse 'attributes' section""" + if "attributes" not in attrs: + return "" + lines =3D [self.fmt.rst_fields("attributes", self.fmt.rst_list_inl= ine(attrs["attributes"]), level + 1)] + + return "\n".join(lines) + + + def parse_operations(self, operations: List[Dict[str, Any]], namespace= : str) -> str: + """Parse operations block""" + preprocessed =3D ["name", "doc", "title", "do", "dump", "flags"] + linkable =3D ["fixed-header", "attribute-set"] + lines =3D [] + + for operation in operations: + lines.append(self.fmt.rst_section(namespace, 'operation', oper= ation["name"])) + lines.append(self.fmt.rst_paragraph(operation["doc"]) + "\n") + + for key in operation.keys(): + if key in preprocessed: + # Skip the special fields + continue + value =3D operation[key] + if key in linkable: + value =3D self.fmt.rst_ref(namespace, key, value) + lines.append(self.fmt.rst_fields(key, value, 0)) + if 'flags' in operation: + lines.append(self.fmt.rst_fields('flags', self.fmt.rst_lis= t_inline(operation['flags']))) + + if "do" in operation: + lines.append(self.fmt.rst_paragraph(":do:", 0)) + lines.append(self.parse_do(operation["do"], 0)) + if "dump" in operation: + lines.append(self.fmt.rst_paragraph(":dump:", 0)) + lines.append(self.parse_do(operation["dump"], 0)) + + # New line after fields + lines.append("\n") + + return "\n".join(lines) + + + def parse_entries(self, entries: List[Dict[str, Any]], level: int) -> = str: + """Parse a list of entries""" + ignored =3D ["pad"] + lines =3D [] + for entry in entries: + if isinstance(entry, dict): + # entries could be a list or a dictionary + field_name =3D entry.get("name", "") + if field_name in ignored: + continue + type_ =3D entry.get("type") + if type_: + field_name +=3D f" ({self.fmt.inline(type_)})" + lines.append( + self.fmt.rst_fields(field_name, self.fmt.sanitize(entr= y.get("doc", "")), level) + ) + elif isinstance(entry, list): + lines.append(self.fmt.rst_list_inline(entry, level)) + else: + lines.append(self.fmt.rst_bullet(self.fmt.inline(self.fmt.= sanitize(entry)), level)) + + lines.append("\n") + return "\n".join(lines) + + + def parse_definitions(self, defs: Dict[str, Any], namespace: str) -> s= tr: + """Parse definitions section""" + preprocessed =3D ["name", "entries", "members"] + ignored =3D ["render-max"] # This is not printed + lines =3D [] + + for definition in defs: + lines.append(self.fmt.rst_section(namespace, 'definition', def= inition["name"])) + for k in definition.keys(): + if k in preprocessed + ignored: + continue + lines.append(self.fmt.rst_fields(k, self.fmt.sanitize(defi= nition[k]), 0)) + + # Field list needs to finish with a new line + lines.append("\n") + if "entries" in definition: + lines.append(self.fmt.rst_paragraph(":entries:", 0)) + lines.append(self.parse_entries(definition["entries"], 1)) + if "members" in definition: + lines.append(self.fmt.rst_paragraph(":members:", 0)) + lines.append(self.parse_entries(definition["members"], 1)) + + return "\n".join(lines) + + + def parse_attr_sets(self, entries: List[Dict[str, Any]], namespace: st= r) -> str: + """Parse attribute from attribute-set""" + preprocessed =3D ["name", "type"] + linkable =3D ["enum", "nested-attributes", "struct", "sub-message"] + ignored =3D ["checks"] + lines =3D [] + + for entry in entries: + lines.append(self.fmt.rst_section(namespace, 'attribute-set', = entry["name"])) + for attr in entry["attributes"]: + type_ =3D attr.get("type") + attr_line =3D attr["name"] + if type_: + # Add the attribute type in the same line + attr_line +=3D f" ({self.fmt.inline(type_)})" + + lines.append(self.fmt.rst_subsubsection(attr_line)) + + for k in attr.keys(): + if k in preprocessed + ignored: + continue + if k in linkable: + value =3D self.fmt.rst_ref(namespace, k, attr[k]) + else: + value =3D self.fmt.sanitize(attr[k]) + lines.append(self.fmt.rst_fields(k, value, 0)) + lines.append("\n") + + return "\n".join(lines) + + + def parse_sub_messages(self, entries: List[Dict[str, Any]], namespace:= str) -> str: + """Parse sub-message definitions""" + lines =3D [] + + for entry in entries: + lines.append(self.fmt.rst_section(namespace, 'sub-message', en= try["name"])) + for fmt in entry["formats"]: + value =3D fmt["value"] + + lines.append(self.fmt.rst_bullet(self.fmt.bold(value))) + for attr in ['fixed-header', 'attribute-set']: + if attr in fmt: + lines.append(self.fmt.rst_fields(attr, + self.fmt.rst_ref(namespace= , attr, fmt[attr]), + 1)) + lines.append("\n") + + return "\n".join(lines) + + + def parse_yaml(self, obj: Dict[str, Any]) -> str: + """Format the whole YAML into a RST string""" + lines =3D [] + + # Main header + + family =3D obj['name'] + + lines.append(self.fmt.rst_header()) + lines.append(self.fmt.rst_label("netlink-" + family)) + + title =3D f"Family ``{family}`` netlink specification" + lines.append(self.fmt.rst_title(title)) + lines.append(self.fmt.rst_paragraph(".. contents:: :depth: 3\n")) + + if "doc" in obj: + lines.append(self.fmt.rst_subtitle("Summary")) + lines.append(self.fmt.rst_paragraph(obj["doc"], 0)) + + # Operations + if "operations" in obj: + lines.append(self.fmt.rst_subtitle("Operations")) + lines.append(self.parse_operations(obj["operations"]["list"], = family)) + + # Multicast groups + if "mcast-groups" in obj: + lines.append(self.fmt.rst_subtitle("Multicast groups")) + lines.append(self.parse_mcast_group(obj["mcast-groups"]["list"= ])) + + # Definitions + if "definitions" in obj: + lines.append(self.fmt.rst_subtitle("Definitions")) + lines.append(self.parse_definitions(obj["definitions"], family= )) + + # Attributes set + if "attribute-sets" in obj: + lines.append(self.fmt.rst_subtitle("Attribute sets")) + lines.append(self.parse_attr_sets(obj["attribute-sets"], famil= y)) + + # Sub-messages + if "sub-messages" in obj: + lines.append(self.fmt.rst_subtitle("Sub-messages")) + lines.append(self.parse_sub_messages(obj["sub-messages"], fami= ly)) + + return "\n".join(lines) + + + # Main functions + # =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + + def parse_yaml_file(self, filename: str) -> str: + """Transform the YAML specified by filename into an RST-formatted = string""" + with open(filename, "r", encoding=3D"utf-8") as spec_file: + yaml_data =3D yaml.safe_load(spec_file) + content =3D self.parse_yaml(yaml_data) + + return content + + + def generate_main_index_rst(self, output: str, index_dir: str) -> None: + """Generate the `networking_spec/index` content and write to the f= ile""" + lines =3D [] + + lines.append(self.fmt.rst_header()) + lines.append(self.fmt.rst_label("specs")) + lines.append(self.fmt.rst_title("Netlink Family Specifications")) + lines.append(self.fmt.rst_toctree(1)) + + index_fname =3D os.path.basename(output) + base, ext =3D os.path.splitext(index_fname) + + if not index_dir: + index_dir =3D os.path.dirname(output) + + logging.debug(f"Looking for {ext} files in %s", index_dir) + for filename in sorted(os.listdir(index_dir)): + if not filename.endswith(ext) or filename =3D=3D index_fname: + continue + base, ext =3D os.path.splitext(filename) + lines.append(f" {base}\n") + + logging.debug("Writing an index file at %s", output) + + return "".join(lines) diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index 7bfb8ceeeefc..b5a665eeaa5a 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -10,354 +10,17 @@ =20 This script performs extensive parsing to the Linux kernel's netlink Y= AML spec files, in an effort to avoid needing to heavily mark up the origi= nal - YAML file. - - This code is split in three big parts: - 1) RST formatters: Use to convert a string to a RST output - 2) Parser helpers: Functions to parse the YAML data structure - 3) Main function and small helpers + YAML file. It uses the library code from scripts/lib. """ =20 -from typing import Any, Dict, List import os.path +import pathlib import sys import argparse import logging -import yaml - - -SPACE_PER_LEVEL =3D 4 - - -# RST Formatters -# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -def headroom(level: int) -> str: - """Return space to format""" - return " " * (level * SPACE_PER_LEVEL) - - -def bold(text: str) -> str: - """Format bold text""" - return f"**{text}**" - - -def inline(text: str) -> str: - """Format inline text""" - return f"``{text}``" - - -def sanitize(text: str) -> str: - """Remove newlines and multiple spaces""" - # This is useful for some fields that are spread across multiple lines - return str(text).replace("\n", " ").strip() - - -def rst_fields(key: str, value: str, level: int =3D 0) -> str: - """Return a RST formatted field""" - return headroom(level) + f":{key}: {value}" - - -def rst_definition(key: str, value: Any, level: int =3D 0) -> str: - """Format a single rst definition""" - return headroom(level) + key + "\n" + headroom(level + 1) + str(value) - - -def rst_paragraph(paragraph: str, level: int =3D 0) -> str: - """Return a formatted paragraph""" - return headroom(level) + paragraph - - -def rst_bullet(item: str, level: int =3D 0) -> str: - """Return a formatted a bullet""" - return headroom(level) + f"- {item}" - - -def rst_subsection(title: str) -> str: - """Add a sub-section to the document""" - return f"{title}\n" + "-" * len(title) - - -def rst_subsubsection(title: str) -> str: - """Add a sub-sub-section to the document""" - return f"{title}\n" + "~" * len(title) - - -def rst_section(namespace: str, prefix: str, title: str) -> str: - """Add a section to the document""" - return f".. _{namespace}-{prefix}-{title}:\n\n{title}\n" + "=3D" * len= (title) - - -def rst_subtitle(title: str) -> str: - """Add a subtitle to the document""" - return "\n" + "-" * len(title) + f"\n{title}\n" + "-" * len(title) + "= \n\n" - - -def rst_title(title: str) -> str: - """Add a title to the document""" - return "=3D" * len(title) + f"\n{title}\n" + "=3D" * len(title) + "\n\= n" - - -def rst_list_inline(list_: List[str], level: int =3D 0) -> str: - """Format a list using inlines""" - return headroom(level) + "[" + ", ".join(inline(i) for i in list_) + "= ]" - - -def rst_ref(namespace: str, prefix: str, name: str) -> str: - """Add a hyperlink to the document""" - mappings =3D {'enum': 'definition', - 'fixed-header': 'definition', - 'nested-attributes': 'attribute-set', - 'struct': 'definition'} - if prefix in mappings: - prefix =3D mappings[prefix] - return f":ref:`{namespace}-{prefix}-{name}`" - - -def rst_header() -> str: - """The headers for all the auto generated RST files""" - lines =3D [] - - lines.append(rst_paragraph(".. SPDX-License-Identifier: GPL-2.0")) - lines.append(rst_paragraph(".. NOTE: This document was auto-generated.= \n\n")) - - return "\n".join(lines) - - -def rst_toctree(maxdepth: int =3D 2) -> str: - """Generate a toctree RST primitive""" - lines =3D [] - - lines.append(".. toctree::") - lines.append(f" :maxdepth: {maxdepth}\n\n") - - return "\n".join(lines) - - -def rst_label(title: str) -> str: - """Return a formatted label""" - return f".. _{title}:\n\n" - - -# Parsers -# =3D=3D=3D=3D=3D=3D=3D - - -def parse_mcast_group(mcast_group: List[Dict[str, Any]]) -> str: - """Parse 'multicast' group list and return a formatted string""" - lines =3D [] - for group in mcast_group: - lines.append(rst_bullet(group["name"])) - - return "\n".join(lines) - - -def parse_do(do_dict: Dict[str, Any], level: int =3D 0) -> str: - """Parse 'do' section and return a formatted string""" - lines =3D [] - for key in do_dict.keys(): - lines.append(rst_paragraph(bold(key), level + 1)) - if key in ['request', 'reply']: - lines.append(parse_do_attributes(do_dict[key], level + 1) + "\= n") - else: - lines.append(headroom(level + 2) + do_dict[key] + "\n") - - return "\n".join(lines) - - -def parse_do_attributes(attrs: Dict[str, Any], level: int =3D 0) -> str: - """Parse 'attributes' section""" - if "attributes" not in attrs: - return "" - lines =3D [rst_fields("attributes", rst_list_inline(attrs["attributes"= ]), level + 1)] - - return "\n".join(lines) - - -def parse_operations(operations: List[Dict[str, Any]], namespace: str) -> = str: - """Parse operations block""" - preprocessed =3D ["name", "doc", "title", "do", "dump", "flags"] - linkable =3D ["fixed-header", "attribute-set"] - lines =3D [] - - for operation in operations: - lines.append(rst_section(namespace, 'operation', operation["name"]= )) - lines.append(rst_paragraph(operation["doc"]) + "\n") - - for key in operation.keys(): - if key in preprocessed: - # Skip the special fields - continue - value =3D operation[key] - if key in linkable: - value =3D rst_ref(namespace, key, value) - lines.append(rst_fields(key, value, 0)) - if 'flags' in operation: - lines.append(rst_fields('flags', rst_list_inline(operation['fl= ags']))) - - if "do" in operation: - lines.append(rst_paragraph(":do:", 0)) - lines.append(parse_do(operation["do"], 0)) - if "dump" in operation: - lines.append(rst_paragraph(":dump:", 0)) - lines.append(parse_do(operation["dump"], 0)) - - # New line after fields - lines.append("\n") - - return "\n".join(lines) - - -def parse_entries(entries: List[Dict[str, Any]], level: int) -> str: - """Parse a list of entries""" - ignored =3D ["pad"] - lines =3D [] - for entry in entries: - if isinstance(entry, dict): - # entries could be a list or a dictionary - field_name =3D entry.get("name", "") - if field_name in ignored: - continue - type_ =3D entry.get("type") - if type_: - field_name +=3D f" ({inline(type_)})" - lines.append( - rst_fields(field_name, sanitize(entry.get("doc", "")), lev= el) - ) - elif isinstance(entry, list): - lines.append(rst_list_inline(entry, level)) - else: - lines.append(rst_bullet(inline(sanitize(entry)), level)) - - lines.append("\n") - return "\n".join(lines) - - -def parse_definitions(defs: Dict[str, Any], namespace: str) -> str: - """Parse definitions section""" - preprocessed =3D ["name", "entries", "members"] - ignored =3D ["render-max"] # This is not printed - lines =3D [] - - for definition in defs: - lines.append(rst_section(namespace, 'definition', definition["name= "])) - for k in definition.keys(): - if k in preprocessed + ignored: - continue - lines.append(rst_fields(k, sanitize(definition[k]), 0)) - - # Field list needs to finish with a new line - lines.append("\n") - if "entries" in definition: - lines.append(rst_paragraph(":entries:", 0)) - lines.append(parse_entries(definition["entries"], 1)) - if "members" in definition: - lines.append(rst_paragraph(":members:", 0)) - lines.append(parse_entries(definition["members"], 1)) - - return "\n".join(lines) - - -def parse_attr_sets(entries: List[Dict[str, Any]], namespace: str) -> str: - """Parse attribute from attribute-set""" - preprocessed =3D ["name", "type"] - linkable =3D ["enum", "nested-attributes", "struct", "sub-message"] - ignored =3D ["checks"] - lines =3D [] - - for entry in entries: - lines.append(rst_section(namespace, 'attribute-set', entry["name"]= )) - for attr in entry["attributes"]: - type_ =3D attr.get("type") - attr_line =3D attr["name"] - if type_: - # Add the attribute type in the same line - attr_line +=3D f" ({inline(type_)})" - - lines.append(rst_subsubsection(attr_line)) - - for k in attr.keys(): - if k in preprocessed + ignored: - continue - if k in linkable: - value =3D rst_ref(namespace, k, attr[k]) - else: - value =3D sanitize(attr[k]) - lines.append(rst_fields(k, value, 0)) - lines.append("\n") - - return "\n".join(lines) - - -def parse_sub_messages(entries: List[Dict[str, Any]], namespace: str) -> s= tr: - """Parse sub-message definitions""" - lines =3D [] - - for entry in entries: - lines.append(rst_section(namespace, 'sub-message', entry["name"])) - for fmt in entry["formats"]: - value =3D fmt["value"] - - lines.append(rst_bullet(bold(value))) - for attr in ['fixed-header', 'attribute-set']: - if attr in fmt: - lines.append(rst_fields(attr, - rst_ref(namespace, attr, fmt[a= ttr]), - 1)) - lines.append("\n") - - return "\n".join(lines) - - -def parse_yaml(obj: Dict[str, Any]) -> str: - """Format the whole YAML into a RST string""" - lines =3D [] - - # Main header - - family =3D obj['name'] - - lines.append(rst_header()) - lines.append(rst_label("netlink-" + family)) - - title =3D f"Family ``{family}`` netlink specification" - lines.append(rst_title(title)) - lines.append(rst_paragraph(".. contents:: :depth: 3\n")) - - if "doc" in obj: - lines.append(rst_subtitle("Summary")) - lines.append(rst_paragraph(obj["doc"], 0)) - - # Operations - if "operations" in obj: - lines.append(rst_subtitle("Operations")) - lines.append(parse_operations(obj["operations"]["list"], family)) - - # Multicast groups - if "mcast-groups" in obj: - lines.append(rst_subtitle("Multicast groups")) - lines.append(parse_mcast_group(obj["mcast-groups"]["list"])) - - # Definitions - if "definitions" in obj: - lines.append(rst_subtitle("Definitions")) - lines.append(parse_definitions(obj["definitions"], family)) - - # Attributes set - if "attribute-sets" in obj: - lines.append(rst_subtitle("Attribute sets")) - lines.append(parse_attr_sets(obj["attribute-sets"], family)) - - # Sub-messages - if "sub-messages" in obj: - lines.append(rst_subtitle("Sub-messages")) - lines.append(parse_sub_messages(obj["sub-messages"], family)) - - return "\n".join(lines) - - -# Main functions -# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +sys.path.append(pathlib.Path(__file__).resolve().parent.as_posix()) +from lib import YnlDocGenerator # pylint: disable=3DC0413 =20 def parse_arguments() -> argparse.Namespace: """Parse arguments from user""" @@ -392,15 +55,6 @@ def parse_arguments() -> argparse.Namespace: return args =20 =20 -def parse_yaml_file(filename: str) -> str: - """Transform the YAML specified by filename into an RST-formatted stri= ng""" - with open(filename, "r", encoding=3D"utf-8") as spec_file: - yaml_data =3D yaml.safe_load(spec_file) - content =3D parse_yaml(yaml_data) - - return content - - def write_to_rstfile(content: str, filename: str) -> None: """Write the generated content into an RST file""" logging.debug("Saving RST file to %s", filename) @@ -411,7 +65,6 @@ def write_to_rstfile(content: str, filename: str) -> Non= e: =20 def generate_main_index_rst(output: str) -> None: """Generate the `networking_spec/index` content and write to the file"= "" - lines =3D [] =20 lines.append(rst_header()) lines.append(rst_label("specs")) @@ -426,7 +79,7 @@ def generate_main_index_rst(output: str) -> None: lines.append(f" {filename.replace('.rst', '')}\n") =20 logging.debug("Writing an index file at %s", output) - write_to_rstfile("".join(lines), output) + write_to_rstfile(msg, output) =20 =20 def main() -> None: @@ -434,10 +87,12 @@ def main() -> None: =20 args =3D parse_arguments() =20 + parser =3D YnlDocGenerator() + if args.input: logging.debug("Parsing %s", args.input) try: - content =3D parse_yaml_file(os.path.join(args.input)) + content =3D parser.parse_yaml_file(os.path.join(args.input)) except Exception as exception: logging.warning("Failed to parse %s.", args.input) logging.warning(exception) --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 C637D2BEC3F; Wed, 18 Jun 2025 11:46:51 +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=1750247211; cv=none; b=Ekq+KSpA5UU8xoDa807Xq0si3+OaWtiXqppaHQvXM+fbikICAmwFikZ51iiyRG6rVuJtMlHCfJuKYaXwFv08Hc/EbW508SZvLdu+AhTdxKDBIJ25UoYiqPVLESqMsaxx2uYzStiDo2MBtLf8VzjTieRf+R8Lw5GQbbK2JUdMkPE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247211; c=relaxed/simple; bh=Hv3gLw50JLGG5g7ccl776oKGKqF7lxHBB7tVJrn/eaQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=TRpctvHH2+ueL0QUqKiIjmUBIY2e2driYeyL1IYfLjtyLxKSeStsilRGLWM/zeQ3qoSZLGHz7qvLQM40pMHItbIJkHWW5/VNPTsh568OESQN8z5dk+xyWzsRXr3lKGjT0Ch1UTCCyXLJKYBX7J5r/In1Ptf3OVbO5Tv0Puogf7A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Hr6Z57a3; 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="Hr6Z57a3" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 66690C4CEF4; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=Hv3gLw50JLGG5g7ccl776oKGKqF7lxHBB7tVJrn/eaQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hr6Z57a3juhMa/tARGa4WTOcB7PeTRPuzl0CYxiGCCurhYGvSo74ISWo6DVkJgdpl 6dohbAY9J+ERcWMPgLhJ0Je0N3xc6Eyg29g6rva8tyHW0tjWQwjtDcpjhPo/sKRX+1 dVfSKv1a26OE7M16QzqZus9XAUlfYUG3D4mmlx3eYDnnps2JVT2RtFYYSl2VLEjM2m ws+yPl7YkMvKBz604fXe4t814XndrOn+WRlo/8lJgakSMsuMe2Q3GnZxRIkRVoFOEb SPzntBSBlq3xItX6uqfvP2tGGdKFx7lq2YiKmYbgkBfnAazJppPHZxcL5IKlesvxgu jvO+Gs9iAF1Iw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036UZ-2Luw; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 05/15] docs: netlink: index.rst: add a netlink index file Date: Wed, 18 Jun 2025 13:46:32 +0200 Message-ID: <468efe892aecc585288a3fcdbecc1db7d4871196.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Instead of generating the index file, use glob to automatically include all data from yaml. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Donald Hunter --- Documentation/netlink/specs/index.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 Documentation/netlink/specs/index.rst diff --git a/Documentation/netlink/specs/index.rst b/Documentation/netlink/= specs/index.rst new file mode 100644 index 000000000000..7f7cf4a096f2 --- /dev/null +++ b/Documentation/netlink/specs/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _specs: + +=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 +Netlink Family Specifications +=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 + +.. toctree:: + :maxdepth: 1 + :glob: + + * --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 410822DE1FE; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=ZlsI+j61IjfaChx7Mm1pA5X+kPdbRD1dVTJtc11gA//TfPAqz3sGwuegn1BSlbNS6iaDZDA7cvZZYP71EiekLPDJ6e549Vuf7hZK+P+6R/XXFe5aQkjzdlMLRjUUpX2IT2QVjII/sQzvBbfJS70DJi+4rw3MxRbqC+B6Wmcj8oo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=eN7Fxcj9u2QqSQyAPJebfF4efSTAdGEp6Mz6tU0QxYE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=I9G1iYmC5yEAioCGvMk0scdpoM+Kc3sYmUYKnuktcczjkyvANmMBhwGXre89L3ovg0HAj6iw57pco9EAs1NXr/cdAvhtraXaFnWX6UmX9eS28VBCDcaWg2ePsk0L+KyXdfW4oQfn6pzvfiyLm/Ouwz+afPXXhMmM9000PYNfhJ8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Y5qc8JaJ; 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="Y5qc8JaJ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5CEFFC4CEED; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=eN7Fxcj9u2QqSQyAPJebfF4efSTAdGEp6Mz6tU0QxYE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Y5qc8JaJNngjt5xMMheiWdiT5Wlm8grh5TwZ1cD6MlIwizBMNsDymDJpvfRkNCK9o 3TnRvnOP2kJWm1tU9GppCQL3CTntdL45YRWCoLr9ao4rxD2txtncHbMEYclr/Ndt8n +ceJtJCCeHUr12jWouOdarnQ6hcdzydUCSMhLlFs3L6CGAx3z0kpaPsCEeY4kYCL8H HOp6EasctSH7p6t1CN6a1qP2o3Xf2YQe3UpT6UQr/g3mI1aAdRiXAZQHeBu8GXY/c4 Di2ERh2ZFJwjCWTN7cVgo4xObZks/wdh5gNt7LTUn5PTWxEPWBf6Jg/bDSadopaA0w Rfi+q2CO8WTMw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036Ue-2T7y; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 06/15] tools: ynl_gen_rst.py: cleanup coding style Date: Wed, 18 Jun 2025 13:46:33 +0200 Message-ID: <901d329a2d679e05572eb399b39418a48a491844.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Cleanup some coding style issues pointed by pylint and flake8. No functional changes. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Breno Leitao --- tools/net/ynl/pyynl/lib/doc_generator.py | 75 ++++++++---------------- 1 file changed, 26 insertions(+), 49 deletions(-) diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl= /lib/doc_generator.py index 839e78b39de3..f71360f0ceb7 100644 --- a/tools/net/ynl/pyynl/lib/doc_generator.py +++ b/tools/net/ynl/pyynl/lib/doc_generator.py @@ -18,17 +18,12 @@ """ =20 from typing import Any, Dict, List -import os.path -import sys -import argparse -import logging import yaml =20 =20 -# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -# RST Formatters -# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D class RstFormatters: + """RST Formatters""" + SPACE_PER_LEVEL =3D 4 =20 @staticmethod @@ -36,81 +31,67 @@ class RstFormatters: """Return space to format""" return " " * (level * RstFormatters.SPACE_PER_LEVEL) =20 - @staticmethod def bold(text: str) -> str: """Format bold text""" return f"**{text}**" =20 - @staticmethod def inline(text: str) -> str: """Format inline text""" return f"``{text}``" =20 - @staticmethod def sanitize(text: str) -> str: """Remove newlines and multiple spaces""" # This is useful for some fields that are spread across multiple l= ines return str(text).replace("\n", " ").strip() =20 - def rst_fields(self, key: str, value: str, level: int =3D 0) -> str: """Return a RST formatted field""" return self.headroom(level) + f":{key}: {value}" =20 - def rst_definition(self, key: str, value: Any, level: int =3D 0) -> st= r: """Format a single rst definition""" return self.headroom(level) + key + "\n" + self.headroom(level + 1= ) + str(value) =20 - def rst_paragraph(self, paragraph: str, level: int =3D 0) -> str: """Return a formatted paragraph""" return self.headroom(level) + paragraph =20 - def rst_bullet(self, item: str, level: int =3D 0) -> str: """Return a formatted a bullet""" return self.headroom(level) + f"- {item}" =20 - @staticmethod def rst_subsection(title: str) -> str: """Add a sub-section to the document""" return f"{title}\n" + "-" * len(title) =20 - @staticmethod def rst_subsubsection(title: str) -> str: """Add a sub-sub-section to the document""" return f"{title}\n" + "~" * len(title) =20 - @staticmethod def rst_section(namespace: str, prefix: str, title: str) -> str: """Add a section to the document""" return f".. _{namespace}-{prefix}-{title}:\n\n{title}\n" + "=3D" *= len(title) =20 - @staticmethod def rst_subtitle(title: str) -> str: """Add a subtitle to the document""" return "\n" + "-" * len(title) + f"\n{title}\n" + "-" * len(title)= + "\n\n" =20 - @staticmethod def rst_title(title: str) -> str: """Add a title to the document""" return "=3D" * len(title) + f"\n{title}\n" + "=3D" * len(title) + = "\n\n" =20 - def rst_list_inline(self, list_: List[str], level: int =3D 0) -> str: """Format a list using inlines""" return self.headroom(level) + "[" + ", ".join(self.inline(i) for i= in list_) + "]" =20 - @staticmethod def rst_ref(namespace: str, prefix: str, name: str) -> str: """Add a hyperlink to the document""" @@ -119,10 +100,9 @@ class RstFormatters: 'nested-attributes': 'attribute-set', 'struct': 'definition'} if prefix in mappings: - prefix =3D mappings[prefix] + prefix =3D mappings.get(prefix, "") return f":ref:`{namespace}-{prefix}-{name}`" =20 - def rst_header(self) -> str: """The headers for all the auto generated RST files""" lines =3D [] @@ -132,7 +112,6 @@ class RstFormatters: =20 return "\n".join(lines) =20 - @staticmethod def rst_toctree(maxdepth: int =3D 2) -> str: """Generate a toctree RST primitive""" @@ -143,16 +122,13 @@ class RstFormatters: =20 return "\n".join(lines) =20 - @staticmethod def rst_label(title: str) -> str: """Return a formatted label""" return f".. _{title}:\n\n" =20 -# =3D=3D=3D=3D=3D=3D=3D -# Parsers -# =3D=3D=3D=3D=3D=3D=3D class YnlDocGenerator: + """YAML Netlink specs Parser""" =20 fmt =3D RstFormatters() =20 @@ -164,7 +140,6 @@ class YnlDocGenerator: =20 return "\n".join(lines) =20 - def parse_do(self, do_dict: Dict[str, Any], level: int =3D 0) -> str: """Parse 'do' section and return a formatted string""" lines =3D [] @@ -177,16 +152,16 @@ class YnlDocGenerator: =20 return "\n".join(lines) =20 - def parse_do_attributes(self, attrs: Dict[str, Any], level: int =3D 0)= -> str: """Parse 'attributes' section""" if "attributes" not in attrs: return "" - lines =3D [self.fmt.rst_fields("attributes", self.fmt.rst_list_inl= ine(attrs["attributes"]), level + 1)] + lines =3D [self.fmt.rst_fields("attributes", + self.fmt.rst_list_inline(attrs["attri= butes"]), + level + 1)] =20 return "\n".join(lines) =20 - def parse_operations(self, operations: List[Dict[str, Any]], namespace= : str) -> str: """Parse operations block""" preprocessed =3D ["name", "doc", "title", "do", "dump", "flags"] @@ -194,7 +169,8 @@ class YnlDocGenerator: lines =3D [] =20 for operation in operations: - lines.append(self.fmt.rst_section(namespace, 'operation', oper= ation["name"])) + lines.append(self.fmt.rst_section(namespace, 'operation', + operation["name"])) lines.append(self.fmt.rst_paragraph(operation["doc"]) + "\n") =20 for key in operation.keys(): @@ -206,7 +182,8 @@ class YnlDocGenerator: value =3D self.fmt.rst_ref(namespace, key, value) lines.append(self.fmt.rst_fields(key, value, 0)) if 'flags' in operation: - lines.append(self.fmt.rst_fields('flags', self.fmt.rst_lis= t_inline(operation['flags']))) + lines.append(self.fmt.rst_fields('flags', + self.fmt.rst_list_inline(= operation['flags']))) =20 if "do" in operation: lines.append(self.fmt.rst_paragraph(":do:", 0)) @@ -220,7 +197,6 @@ class YnlDocGenerator: =20 return "\n".join(lines) =20 - def parse_entries(self, entries: List[Dict[str, Any]], level: int) -> = str: """Parse a list of entries""" ignored =3D ["pad"] @@ -235,17 +211,19 @@ class YnlDocGenerator: if type_: field_name +=3D f" ({self.fmt.inline(type_)})" lines.append( - self.fmt.rst_fields(field_name, self.fmt.sanitize(entr= y.get("doc", "")), level) + self.fmt.rst_fields(field_name, + self.fmt.sanitize(entry.get("doc",= "")), + level) ) elif isinstance(entry, list): lines.append(self.fmt.rst_list_inline(entry, level)) else: - lines.append(self.fmt.rst_bullet(self.fmt.inline(self.fmt.= sanitize(entry)), level)) + lines.append(self.fmt.rst_bullet(self.fmt.inline(self.fmt.= sanitize(entry)), + level)) =20 lines.append("\n") return "\n".join(lines) =20 - def parse_definitions(self, defs: Dict[str, Any], namespace: str) -> s= tr: """Parse definitions section""" preprocessed =3D ["name", "entries", "members"] @@ -270,7 +248,6 @@ class YnlDocGenerator: =20 return "\n".join(lines) =20 - def parse_attr_sets(self, entries: List[Dict[str, Any]], namespace: st= r) -> str: """Parse attribute from attribute-set""" preprocessed =3D ["name", "type"] @@ -279,7 +256,8 @@ class YnlDocGenerator: lines =3D [] =20 for entry in entries: - lines.append(self.fmt.rst_section(namespace, 'attribute-set', = entry["name"])) + lines.append(self.fmt.rst_section(namespace, 'attribute-set', + entry["name"])) for attr in entry["attributes"]: type_ =3D attr.get("type") attr_line =3D attr["name"] @@ -301,13 +279,13 @@ class YnlDocGenerator: =20 return "\n".join(lines) =20 - def parse_sub_messages(self, entries: List[Dict[str, Any]], namespace:= str) -> str: """Parse sub-message definitions""" lines =3D [] =20 for entry in entries: - lines.append(self.fmt.rst_section(namespace, 'sub-message', en= try["name"])) + lines.append(self.fmt.rst_section(namespace, 'sub-message', + entry["name"])) for fmt in entry["formats"]: value =3D fmt["value"] =20 @@ -315,13 +293,14 @@ class YnlDocGenerator: for attr in ['fixed-header', 'attribute-set']: if attr in fmt: lines.append(self.fmt.rst_fields(attr, - self.fmt.rst_ref(namespace= , attr, fmt[attr]), - 1)) + self.fmt.rst_ref(= namespace, + = attr, + = fmt[attr]), + 1)) lines.append("\n") =20 return "\n".join(lines) =20 - def parse_yaml(self, obj: Dict[str, Any]) -> str: """Format the whole YAML into a RST string""" lines =3D [] @@ -344,7 +323,8 @@ class YnlDocGenerator: # Operations if "operations" in obj: lines.append(self.fmt.rst_subtitle("Operations")) - lines.append(self.parse_operations(obj["operations"]["list"], = family)) + lines.append(self.parse_operations(obj["operations"]["list"], + family)) =20 # Multicast groups if "mcast-groups" in obj: @@ -368,11 +348,9 @@ class YnlDocGenerator: =20 return "\n".join(lines) =20 - # Main functions # =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 - def parse_yaml_file(self, filename: str) -> str: """Transform the YAML specified by filename into an RST-formatted = string""" with open(filename, "r", encoding=3D"utf-8") as spec_file: @@ -381,7 +359,6 @@ class YnlDocGenerator: =20 return content =20 - def generate_main_index_rst(self, output: str, index_dir: str) -> None: """Generate the `networking_spec/index` content and write to the f= ile""" lines =3D [] --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 C05702BD5A8; Wed, 18 Jun 2025 11:46:51 +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=1750247211; cv=none; b=q33oCey69G6dzO4IAQF5T3ibp60BaNC+jMF8cgio6NFKNX1gfqSIb0QYDqD+kis2FHhYwXrntClprq61JqeYcJYPDD8reja5A17L/wf5OpPTKtwVUjo7eIlcvVdB4d6eiQqKqE+hJNLDMI3kYwTmcTTrNoK3u+tQTpjBiNp+6X8= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247211; c=relaxed/simple; bh=2WQh1GG+XNK0Cdx26utHd/0dTt1jIj+urA1wFYdPe3Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=pxxBrYmCtAVY0WYJVryNJ+SYznnEFWVDzQu8KD2ZSJiKU1Ju5X+KVkOEMzh6S0bYhG4uKiqUoRNR1wbJ65jm4Cyk11uaBX/yL0TR2dCsO2bykLrNSngpojn8wbkaz3HB7mZrkLcVLg1cMFimxrJ+GrA+JbJRhSJToUrngYcB2y0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Et/iFfWl; 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="Et/iFfWl" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 5F1A2C4CEF1; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=2WQh1GG+XNK0Cdx26utHd/0dTt1jIj+urA1wFYdPe3Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Et/iFfWlcEzL1weQEhp1I6Pui5hYu/hp3TJMhAoXcVq8ea80Zxx5TokBskCTwuIPz 5uuvGVFIMhSkYgqxVHO1R5m02uUl5/NefK4kVdJSKBMInXC0YXpvBk95DWMArrgaXT 7RK8dk6IaTnwaqWuCUCDZ3JU+tnXU95vumeY7ADbVLgRcBY/ZzKarJceOdpztOhvWp GelUU/P0v0AKeFv+IANrrN7Bz6ZR018Vt8kMqS4UwY91qkeBzwnG1X+FP9VlxP0ePN mNyDpZf9WeF6/VLYOPkXGQFRKcPlOJvMl1Nns8z6rUa7DcS4rEn6rUzCLS3KBXGsue b8x0NlWtfP2yg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036Uh-2Zyf; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 07/15] docs: sphinx: add a parser for yaml files for Netlink specs Date: Wed, 18 Jun 2025 13:46:34 +0200 Message-ID: <79fd88d84e63351d1156a343d697d9bbca8159c5.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Add a simple sphinx.Parser to handle yaml files and add the the code to handle Netlink specs. All other yaml files are ignored. The code was written in a way that parsing yaml for different subsystems and even for different parts of Netlink are easy. All it takes to have a different parser is to add an import line similar to: from netlink_yml_parser import YnlDocGenerator adding the corresponding parser somewhere at the extension: netlink_parser =3D YnlDocGenerator() And then add a logic inside parse() to handle different doc outputs, depending on the file location, similar to: if "/netlink/specs/" in fname: msg =3D self.netlink_parser.parse_yaml_file(fname) Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/parser_yaml.py | 76 +++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100755 Documentation/sphinx/parser_yaml.py diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/par= ser_yaml.py new file mode 100755 index 000000000000..635945e1c5ba --- /dev/null +++ b/Documentation/sphinx/parser_yaml.py @@ -0,0 +1,76 @@ +""" +Sphinx extension for processing YAML files +""" + +import os +import re +import sys + +from pprint import pformat + +from docutils.parsers.rst import Parser as RSTParser +from docutils.statemachine import ViewList + +from sphinx.util import logging +from sphinx.parsers import Parser + +srctree =3D os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "tools/net/ynl/pyynl")) + +from netlink_yml_parser import YnlDocGenerator # pylint: disable=3D= C0413 + +logger =3D logging.getLogger(__name__) + +class YamlParser(Parser): + """Custom parser for YAML files.""" + + # Need at least two elements on this set + supported =3D ('yaml', 'yml') + + netlink_parser =3D YnlDocGenerator() + + def do_parse(self, inputstring, document, msg): + """Parse YAML and generate a document tree.""" + + self.setup_parse(inputstring, document) + + result =3D ViewList() + + try: + # Parse message with RSTParser + for i, line in enumerate(msg.split('\n')): + result.append(line, document.current_source, i) + + rst_parser =3D RSTParser() + rst_parser.parse('\n'.join(result), document) + + except Exception as e: + document.reporter.error("YAML parsing error: %s" % pformat(e)) + + self.finish_parse() + + # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser + def parse(self, inputstring, document): + """Check if a YAML is meant to be parsed.""" + + fname =3D document.current_source + + # Handle netlink yaml specs + if "/netlink/specs/" in fname: + msg =3D self.netlink_parser.parse_yaml_file(fname) + self.do_parse(inputstring, document, msg) + + # All other yaml files are ignored + +def setup(app): + """Setup function for the Sphinx extension.""" + + # Add YAML parser + app.add_source_parser(YamlParser) + app.add_source_suffix('.yaml', 'yaml') + + return { + 'version': '1.0', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 4338D2DE200; Wed, 18 Jun 2025 11:46:51 +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=1750247212; cv=none; b=cATNM32Rmjm8HWUzW8AalrY4WrID29m7IycE61moZJ1ajBhh/aCsfy18h8ara6eipGldH5L2DpgaNCP5idsJhitHfet30n+l3JdjM9MokE6j2pfgGd9vBOZSFTM4ekpADVNIQi4nCGLM4gWhfmXp1nue+B2YF5MSQpmyx+GpVDM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=x9AeS/miPbBkEF42gU7I9M77AvT46AbR0fPXxclljq0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Z6hZv01UfYBM0ekIk5u1AfSDz2ss6zoFq3+c+LgtmZf1SiV1As9xO/NOTuqXlQbcFUN/Gq8rmhEH1KVBURrhfbNILfrZljqTGie2cC6nWY6KeujMs3xgme6Zg/m924d1H8V++5K/jiESKDVNnyj/L5QMLDdDpt15e6S9hMTBozw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FDsXTwvB; 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="FDsXTwvB" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7083DC4CEF5; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=x9AeS/miPbBkEF42gU7I9M77AvT46AbR0fPXxclljq0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FDsXTwvBmZ6inEQ0GHo42mMBV2jpCmnV6UZth+MhAXsZj69ehsYRseecuhiPyrVTW S0ht994iFisgUxnwl7UoJAanhfHukyaGk8AzxJZ0qQkwdoljdhIJNPE7NCh7bEX/uT WRf/rTeIyIgLCtivY3No7sqKzGxXtxbdBDVM/mb78sajFjiMZ0SNadSoM8CC2D7MBF lAG1kFAGLJlurI5MPWr4hWWHbKuMJQwOAfieIxNXoOHaiP6DZNN4MOtuBmUBICtdYk YaSVhzrRAhTXdR/RzNYEoYYWknYeaIDyqpFmImvsJUry3ouhuq3fBpbwBM+t3iXyiu 2uQ4hKjUkB9Hg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036Um-2hSN; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 08/15] docs: use parser_yaml extension to handle Netlink specs Date: Wed, 18 Jun 2025 13:46:35 +0200 Message-ID: <4ee82983b4702f4c52296c3bae9c5be8b452650a.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Instead of manually calling ynl_gen_rst.py, use a Sphinx extension. This way, no .rst files would be written to the Kernel source directories. We are using here a toctree with :glob: property. This way, there is no need to touch the netlink/specs/index.rst file every time a new Netlink spec is added/renamed/removed. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Donald Hunter --- Documentation/Makefile | 17 ---------------- Documentation/conf.py | 20 ++++++++++++++----- Documentation/networking/index.rst | 2 +- .../networking/netlink_spec/readme.txt | 4 ---- Documentation/sphinx/parser_yaml.py | 4 ++-- 5 files changed, 18 insertions(+), 29 deletions(-) delete mode 100644 Documentation/networking/netlink_spec/readme.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index b98477df5ddf..820f07e0afe6 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -104,22 +104,6 @@ quiet_cmd_sphinx =3D SPHINX $@ --> file://$(abspath $= (BUILDDIR)/$3/$4) cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(= DOCS_CSS)) $(BUILDDIR)/$3/_static/; \ fi =20 -YNL_INDEX:=3D$(srctree)/Documentation/networking/netlink_spec/index.rst -YNL_RST_DIR:=3D$(srctree)/Documentation/networking/netlink_spec -YNL_YAML_DIR:=3D$(srctree)/Documentation/netlink/specs -YNL_TOOL:=3D$(srctree)/tools/net/ynl/pyynl/ynl_gen_rst.py - -YNL_RST_FILES_TMP :=3D $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/= *.yaml)) -YNL_RST_FILES :=3D $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_= FILES_TMP)) - -$(YNL_INDEX): $(YNL_RST_FILES) - $(Q)$(YNL_TOOL) -o $@ -x - -$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL) - $(Q)$(YNL_TOOL) -i $< -o $@ - -htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX) - htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) @@ -186,7 +170,6 @@ refcheckdocs: $(Q)cd $(srctree);scripts/documentation-file-ref-check =20 cleandocs: - $(Q)rm -f $(YNL_INDEX) $(YNL_RST_FILES) $(Q)rm -rf $(BUILDDIR) $(Q)$(MAKE) BUILDDIR=3D$(abspath $(BUILDDIR)) $(build)=3DDocumentation/us= erspace-api/media clean =20 diff --git a/Documentation/conf.py b/Documentation/conf.py index 4ba4ee45e599..6af61e26cec5 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -38,6 +38,15 @@ exclude_patterns =3D [] dyn_include_patterns =3D [] dyn_exclude_patterns =3D ['output'] =20 +# Currently, only netlink/specs has a parser for yaml. +# Prefer using include patterns if available, as it is faster +if has_include_patterns: + dyn_include_patterns.append('netlink/specs/*.yaml') +else: + dyn_exclude_patterns.append('netlink/*.yaml') + dyn_exclude_patterns.append('devicetree/bindings/**.yaml') + dyn_exclude_patterns.append('core-api/kho/bindings/**.yaml') + # Properly handle include/exclude patterns # ---------------------------------------- =20 @@ -105,7 +114,7 @@ needs_sphinx =3D '3.4.3' extensions =3D ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel', - 'kernel_abi', 'kernel_feat', 'translations'] + 'kernel_abi', 'kernel_feat', 'translations', 'parser_yaml'] =20 # Since Sphinx version 3, the C function parser is more pedantic with rega= rds # to type checking. Due to that, having macros at c:function cause problem= s. @@ -203,10 +212,11 @@ else: # Add any paths that contain templates here, relative to this directory. templates_path =3D ['sphinx/templates'] =20 -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix =3D ['.rst', '.md'] -source_suffix =3D '.rst' +# The suffixes of source filenames that will be automatically parsed +source_suffix =3D { + '.rst': 'restructuredtext', + '.yaml': 'yaml', +} =20 # The encoding of source files. #source_encoding =3D 'utf-8-sig' diff --git a/Documentation/networking/index.rst b/Documentation/networking/= index.rst index ac90b82f3ce9..b7a4969e9bc9 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -57,7 +57,7 @@ Contents: filter generic-hdlc generic_netlink - netlink_spec/index + ../netlink/specs/index gen_stats gtp ila diff --git a/Documentation/networking/netlink_spec/readme.txt b/Documentati= on/networking/netlink_spec/readme.txt deleted file mode 100644 index 030b44aca4e6..000000000000 --- a/Documentation/networking/netlink_spec/readme.txt +++ /dev/null @@ -1,4 +0,0 @@ -SPDX-License-Identifier: GPL-2.0 - -This file is populated during the build of the documentation (htmldocs) by= the -tools/net/ynl/pyynl/ynl_gen_rst.py script. diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/par= ser_yaml.py index 635945e1c5ba..2b2af239a1c2 100755 --- a/Documentation/sphinx/parser_yaml.py +++ b/Documentation/sphinx/parser_yaml.py @@ -15,9 +15,9 @@ from sphinx.util import logging from sphinx.parsers import Parser =20 srctree =3D os.path.abspath(os.environ["srctree"]) -sys.path.insert(0, os.path.join(srctree, "tools/net/ynl/pyynl")) +sys.path.insert(0, os.path.join(srctree, "tools/net/ynl/pyynl/lib")) =20 -from netlink_yml_parser import YnlDocGenerator # pylint: disable=3D= C0413 +from doc_generator import YnlDocGenerator # pylint: disable=3DC0413 =20 logger =3D logging.getLogger(__name__) =20 --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 44B202DE208; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=LbTyyT5vfJIlvkzglSXoOYgP1AOwbSLL91y9Osapw+P+P+iTaY00Q3MHZF30+enWl3+YgFQP6L9EJaT+t5MDBqMJ3f3lmdFX/ZR3PBIP9OOP5sPMaHeTiYppeHRnJDLDpufbZ+j68A/O07E1KY2z+PH5VVSz8Xak1V7Faj7VEIk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=gCUujhjF05O4bN0j1mBzTOE2gqunIOFmC86Oe+w0BHo=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=t2R7Z0AJIvxgl24SXswsQ7OamKiqlEjvopychJsP4rjfFJrYfByjVc2a65+v7xTFcCCSRoAqwV78kiVSaHF0bBhJutsXiDIBUvEtUmBBtZqP+oSo7wzdTR7pynSOnQnOYjaKJDjAAnMBtpWf3LXtm/JmNpF19+/72KGSn8CuTeU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=B3hKuiok; 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="B3hKuiok" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6DFA4C4CEF3; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=gCUujhjF05O4bN0j1mBzTOE2gqunIOFmC86Oe+w0BHo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=B3hKuiokwUIAHVhJAbQbj6y9L1mM6iZ/ZUcWyLY3xwgpIheHmxnQ4iofjmpCbwUpR rUHNjejo5Uo0qMow2ycK1THE2XibdqHxBrpDh+jjFreLRVxC2csqMWkp59iVWup7MF /qOvhYTQ9FbyiYvqCbpGZhzdctfEGHiBKb7oQM/QyJF2S0+wX7B3YNt+chSpUSA4RI dTCuONiUCxqmQdDvQdOIq65C5TF4QqEA3GFya27EK2WWI9WntN/IEjPBVbPXQ/NhPp K28wx1IPMJO21OCLyu/4Ytf+MGt+c2AdIB7do3RNFdRWITQebfZV2jAuxVj/Q28pZT h/AyfOFiwfU0A== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036Up-2owX; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 09/15] docs: uapi: netlink: update netlink specs link Date: Wed, 18 Jun 2025 13:46:36 +0200 Message-ID: <1dbe019319a6fd9f0c672280e079ddad1149cbe4.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" With the recent parser_yaml extension, and the removal of the auto-generated ReST source files, the location of netlink specs changed. Update uAPI accordingly. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Donald Hunter --- Documentation/userspace-api/netlink/index.rst | 2 +- Documentation/userspace-api/netlink/specs.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/= userspace-api/netlink/index.rst index c1b6765cc963..83ae25066591 100644 --- a/Documentation/userspace-api/netlink/index.rst +++ b/Documentation/userspace-api/netlink/index.rst @@ -18,4 +18,4 @@ Netlink documentation for users. =20 See also: - :ref:`Documentation/core-api/netlink.rst ` - - :ref:`Documentation/networking/netlink_spec/index.rst ` + - :ref:`Documentation/netlink/specs/index.rst ` diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/= userspace-api/netlink/specs.rst index 1b50d97d8d7c..debb4bfca5c4 100644 --- a/Documentation/userspace-api/netlink/specs.rst +++ b/Documentation/userspace-api/netlink/specs.rst @@ -15,7 +15,7 @@ kernel headers directly. Internally kernel uses the YAML specs to generate: =20 - the C uAPI header - - documentation of the protocol as a ReST file - see :ref:`Documentation/= networking/netlink_spec/index.rst ` + - documentation of the protocol as a ReST file - see :ref:`Documentation/= netlink/specs/index.rst ` - policy tables for input attribute validation - operation tables =20 --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 409DD2DE1F8; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=kic5xGMlcl+mFkDL65IcMOHs3DkYFWVAuY2yM1pNiOyFdD01USHTy4cRZKi+0v7EeFj55YtA9V1QqQlCzFvB3Zl4KYBBi4dH/43GYH/QgXJTc41qhXf1lH5eEV97lnF7IdpGcbueqJsDccoHHk+cnEEu9tPKkUg6vBvpN4NvO3g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=EpBDvvCEgkXYhfewwIef0GKxoO/B4wVDI6b8/pzv1js=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ShOOFP/IbVcw9McHjAQGA2nH4C/RUyzOMWWFctFR1AcV9m2jgM7PNJgOXFxilFArs+f1vbkyCSwioMLMdlCz8lakE40SoVy6OqoDaWDMKjghYdEms5+VdRbZ3U3bDdThfAK06JWw3IuTgUeG399zB9cnlXGazIUVTdzJwe+c4WE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=W+ZRYobj; 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="W+ZRYobj" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 792B3C4CEF7; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=EpBDvvCEgkXYhfewwIef0GKxoO/B4wVDI6b8/pzv1js=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=W+ZRYobjcLWK0vU17Ws2hevZE0iFBwszhyTYartunBQDEzBnb0bCCXQvtclt7D+3B HVb8Kw/SvOJrc6Frsu2epI4VEzFhYYwkzuMtek/M+XRiU1tq2xwH4zhWDmHs93sVCw d9snjHFdwZr860yuHcxS039luOTnkK2rHxOkcpEOl2S4jV2n4SoTjveEUTv6au9xQ+ SdEs2bbd6a7LHA52uT+H+1XhwNh6Z3KnAr9OYe2/RKlSIgWMbLMyglBSw1Ttrx4aEp JbYCgN+UfW70DIxwBK0gCnsNgYGH29pBOOGDTOjR9SafThcSXmQbP0wdVEteFd+mkd tn/6UdQvq0qIA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036Ut-2w6u; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 10/15] tools: ynl_gen_rst.py: drop support for generating index files Date: Wed, 18 Jun 2025 13:46:37 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" As we're now using an index file with a glob, there's no need to generate index files anymore. Signed-off-by: Mauro Carvalho Chehab --- tools/net/ynl/pyynl/lib/doc_generator.py | 26 ------------------------ tools/net/ynl/pyynl/ynl_gen_rst.py | 26 ------------------------ 2 files changed, 52 deletions(-) diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl= /lib/doc_generator.py index f71360f0ceb7..866551726723 100644 --- a/tools/net/ynl/pyynl/lib/doc_generator.py +++ b/tools/net/ynl/pyynl/lib/doc_generator.py @@ -358,29 +358,3 @@ class YnlDocGenerator: content =3D self.parse_yaml(yaml_data) =20 return content - - def generate_main_index_rst(self, output: str, index_dir: str) -> None: - """Generate the `networking_spec/index` content and write to the f= ile""" - lines =3D [] - - lines.append(self.fmt.rst_header()) - lines.append(self.fmt.rst_label("specs")) - lines.append(self.fmt.rst_title("Netlink Family Specifications")) - lines.append(self.fmt.rst_toctree(1)) - - index_fname =3D os.path.basename(output) - base, ext =3D os.path.splitext(index_fname) - - if not index_dir: - index_dir =3D os.path.dirname(output) - - logging.debug(f"Looking for {ext} files in %s", index_dir) - for filename in sorted(os.listdir(index_dir)): - if not filename.endswith(ext) or filename =3D=3D index_fname: - continue - base, ext =3D os.path.splitext(filename) - lines.append(f" {base}\n") - - logging.debug("Writing an index file at %s", output) - - return "".join(lines) diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index b5a665eeaa5a..90ae19aac89d 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -31,9 +31,6 @@ def parse_arguments() -> argparse.Namespace: =20 # Index and input are mutually exclusive group =3D parser.add_mutually_exclusive_group() - group.add_argument( - "-x", "--index", action=3D"store_true", help=3D"Generate the index= page" - ) group.add_argument("-i", "--input", help=3D"YAML file name") =20 args =3D parser.parse_args() @@ -63,25 +60,6 @@ def write_to_rstfile(content: str, filename: str) -> Non= e: rst_file.write(content) =20 =20 -def generate_main_index_rst(output: str) -> None: - """Generate the `networking_spec/index` content and write to the file"= "" - - lines.append(rst_header()) - lines.append(rst_label("specs")) - lines.append(rst_title("Netlink Family Specifications")) - lines.append(rst_toctree(1)) - - index_dir =3D os.path.dirname(output) - logging.debug("Looking for .rst files in %s", index_dir) - for filename in sorted(os.listdir(index_dir)): - if not filename.endswith(".rst") or filename =3D=3D "index.rst": - continue - lines.append(f" {filename.replace('.rst', '')}\n") - - logging.debug("Writing an index file at %s", output) - write_to_rstfile(msg, output) - - def main() -> None: """Main function that reads the YAML files and generates the RST files= """ =20 @@ -100,10 +78,6 @@ def main() -> None: =20 write_to_rstfile(content, args.output) =20 - if args.index: - # Generate the index RST file - generate_main_index_rst(args.output) - =20 if __name__ =3D=3D "__main__": main() --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 429C32DE1FF; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=pUl1Th6N4ZHiR6xRrdcwlFsO6lIX7aMZyFjZYERlBGhdd4FaZ7TU7iMFPcSE4gl6kqCieCDFiedJhGil/xklfOE+wpTPa9YLuigy/KZNHiTBspumsutM2H2B8HB89YR3EheCKqWRRVdqbiSdvkbH9u4A4mLJFYiA9rHjOpZsmtk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=ogBoG80VZdRt95wsoC2snRc4eLHl6tjexBrTDr8vuXE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=cKnrMxZmYFaJNImOHcjgndumG8B6/ttMkOezAAaaz+tmmWCAH0oSmM0OQZl0vZq1JZLvFAdShd809llE7SLrStJc0wNIwmHFbNspulyv1vohvh2HCbuj29to7owQfHPbm6cAb8gIpj8sHCePAs9iYcL3ieaJN56oDyEUS15el6M= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=MqOWMhVg; 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="MqOWMhVg" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 77690C4CEF6; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=ogBoG80VZdRt95wsoC2snRc4eLHl6tjexBrTDr8vuXE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MqOWMhVgXBtUsi8x3bQXCLmP94NqEgyxWvnIeILMT7qc6HHgMt2mJDyXWnEwzeHQj 5GfF8Z5RF+aXX6MqMfvgLZmfmUnw9x1AcwPrYgolcfB0SacsbH1VoTe7TjamxaS/ye 8TvEWjHleypjBES0T2g1okyv3ecZ4NIRsLqjtXUnTQuaEEr1qmL/WCBPH9nkR0BgXp wE1ew5+oPICvrjkCTUFAYTb91+jPBnnTK2Ea9r6qRB6O0P+sap9rdwunUB8te/Ehkb 5Nrwsry0QB1FJpmN0QJBEUwuWRqh/gVaXoOpKVeJbVzV2INoG+5K5LiKKauy+ytUNV e25+OsXt2vExQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036Uz-33Dh; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 11/15] docs: netlink: remove obsolete .gitignore from unused directory Date: Wed, 18 Jun 2025 13:46:38 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" The previous code was generating source rst files under Documentation/networking/netlink_spec/. With the Sphinx YAML parser, this is now gone. So, stop ignoring *.rst files inside netlink specs directory. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Donald Hunter --- Documentation/networking/netlink_spec/.gitignore | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Documentation/networking/netlink_spec/.gitignore diff --git a/Documentation/networking/netlink_spec/.gitignore b/Documentati= on/networking/netlink_spec/.gitignore deleted file mode 100644 index 30d85567b592..000000000000 --- a/Documentation/networking/netlink_spec/.gitignore +++ /dev/null @@ -1 +0,0 @@ -*.rst --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 48CB32DE213; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=XD4RgyrHqXV/3xiyfnfh364M7HNIpVy/CSL7TjB5ZZQidyNm0Yr8Cop6oQUTZ15DVqz/3QrCkQc9wKk5r7LVlQ4lgBZXnwyx0kEbjs6SzlmK3hZ4P8bWyYJg/URvIUji9bK1BEz0EJIrMCIAOer3gE98UpnR1e9TLqibVQ5uQw4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=NWHr6s5MAHhaxWhvDkXosw3Qmf8A786TTZ4Xlu7HoGk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Dv1hVjnkBH/0f1fWN5j2/Ko34OZGb2HSJHpa/m/j2lCHObi/2DbAcyR702F+PZrAOqZAk6D3guzxsepyn0232ZptDtCT9oLMsjRnqFjQSapi14p2s7tGgcKA4ssaNuKqFKfkcda+/pomKltiTcsAFJTzgD7FCRqbJJbX3Xs5ovQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=cSGAy1pk; 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="cSGAy1pk" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 7F740C4CEF8; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=NWHr6s5MAHhaxWhvDkXosw3Qmf8A786TTZ4Xlu7HoGk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=cSGAy1pkx0lHX7M1U4NRaQlSAbCks10vzCMZ3Lwp7jN7tTyI4o/o7ECCEHeJ1JMi5 7qUZYUs6JZWa3Ygd9xI7P2EO3duNcqsWgQTOZj74iyoyLMbsE8kK36B3yuXl6gNvzP ToSW3nmFsiJs+JatBz4j+i2zJpMd26G0srbgHhKzjpdzW91puiAqGiAk9JRkhF46vc XYai7lwOrfznU/s3N3yi9DYx9NDP00Kh2Nr5TYEoPA3lMdb9wrsNDImBd+1qjagtn/ ir2SNUyrhW6ITKNmdaEeMib51LbIUjaz7bT4aykffehjfTd2D41OWktI0b+uidPe3R cGW7HRjZ+GHtQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036V2-3AR5; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 12/15] MAINTAINERS: add netlink_yml_parser.py to linux-doc Date: Wed, 18 Jun 2025 13:46:39 +0200 Message-ID: <4077605f84d7ba6423dcb5fda4e96ac950856f1d.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" The documentation build depends on the parsing code at ynl_gen_rst.py. Ensure that changes to it will be c/c to linux-doc ML and maintainers by adding an entry for it. This way, if a change there would affect the build, or the minimal version required for Python, doc developers may know in advance. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Breno Leitao --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index a92290fffa16..caa3425e5755 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7202,6 +7202,7 @@ F: scripts/get_abi.py F: scripts/kernel-doc* F: scripts/lib/abi/* F: scripts/lib/kdoc/* +F: tools/net/ynl/pyynl/netlink_yml_parser.py F: scripts/sphinx-pre-install X: Documentation/ABI/ X: Documentation/admin-guide/media/ --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 46D4D2DE20D; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=LT763bLPtpS5heMkhVEqIbSRug02NrRUqXy9d7O//6zvVezyYGvD/Gx9w2XIoATPqZM0MZSBmHgDsUtFTCpWm0fMeMYJBqmvCZLJQeOhtcrl/zkSS49My+1N++xl/Zo8rrWiQGr1/iSeSkBNvtKjOer94BXzS3gpOHdnHzvT194= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=ZRwnGGD63dY02hpT4BqTMDO35vMSt+NPRBYC3eA8F/0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QZm9zPaxqgC4BgiIPcO5T4eT7z2LceM0QSDsAJz/uCYPFpCzco4ACB3mdEGOrwBENMj2wQYlVr5pRPaqTgj7KlZmgakrblhmYcTzO0tDVnzU7xRaH2eDkBMpUuAucMzOD8TYjRlN5eXFr7OEViQhZAsWUYzdqxmKSaYc/Tj/JA0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ECOl5BRe; 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="ECOl5BRe" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8B4D3C4AF0D; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=ZRwnGGD63dY02hpT4BqTMDO35vMSt+NPRBYC3eA8F/0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ECOl5BRe87OvUepxguUsJp/4l1hRNtCbwqNjCMKeGjYqvokOnyKNABZOuwY98Q2fa fCERk7jEx/Ju37vT0DqTitnglMTMQis7idZXo+SwLhbtE61LZmPrs6aBYRHG68NJZd nUMkWxDj1a+YTHrDhD2XHEiyOrQnLUxMXYcKERiMZZ3NhcOnU2BI4NDLhqP7b2fY8A LHfttEj3+Hk8O9XTn9UzR7ttvklSQtu68sg81o9oR7+pX56iGvpm4a9AepBQq13LFX rtTriENeStpvgwr1RmTCLLCMPaoOQeNJfjpkOzFDe6Z1u0qpY3uCnYsTt0MrPhPoM3 em4D2Y/94bjNA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036V7-3HmZ; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 13/15] tools: netlink_yml_parser.py: add line numbers to parsed data Date: Wed, 18 Jun 2025 13:46:40 +0200 Message-ID: <21722a5346cfc3b8a0ad7427fca157cff032e2f0.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" When something goes wrong, we want Sphinx error to point to the right line number from the original source, not from the processed ReST data. Signed-off-by: Mauro Carvalho Chehab --- tools/net/ynl/pyynl/lib/doc_generator.py | 34 ++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl= /lib/doc_generator.py index 866551726723..a9d8ab6f2639 100644 --- a/tools/net/ynl/pyynl/lib/doc_generator.py +++ b/tools/net/ynl/pyynl/lib/doc_generator.py @@ -20,6 +20,16 @@ from typing import Any, Dict, List import yaml =20 +LINE_STR =3D '__lineno__' + +class NumberedSafeLoader(yaml.SafeLoader): + """Override the SafeLoader class to add line number to parsed data""" + + def construct_mapping(self, node): + mapping =3D super().construct_mapping(node) + mapping[LINE_STR] =3D node.start_mark.line + + return mapping =20 class RstFormatters: """RST Formatters""" @@ -127,6 +137,11 @@ class RstFormatters: """Return a formatted label""" return f".. _{title}:\n\n" =20 + @staticmethod + def rst_lineno(lineno: int) -> str: + """Return a lineno comment""" + return f".. LINENO {lineno}\n" + class YnlDocGenerator: """YAML Netlink specs Parser""" =20 @@ -144,6 +159,9 @@ class YnlDocGenerator: """Parse 'do' section and return a formatted string""" lines =3D [] for key in do_dict.keys(): + if key =3D=3D LINE_STR: + lines.append(self.fmt.rst_lineno(do_dict[key])) + continue lines.append(self.fmt.rst_paragraph(self.fmt.bold(key), level = + 1)) if key in ['request', 'reply']: lines.append(self.parse_do_attributes(do_dict[key], level = + 1) + "\n") @@ -174,6 +192,10 @@ class YnlDocGenerator: lines.append(self.fmt.rst_paragraph(operation["doc"]) + "\n") =20 for key in operation.keys(): + if key =3D=3D LINE_STR: + lines.append(self.fmt.rst_lineno(operation[key])) + continue + if key in preprocessed: # Skip the special fields continue @@ -233,6 +255,9 @@ class YnlDocGenerator: for definition in defs: lines.append(self.fmt.rst_section(namespace, 'definition', def= inition["name"])) for k in definition.keys(): + if k =3D=3D LINE_STR: + lines.append(self.fmt.rst_lineno(definition[k])) + continue if k in preprocessed + ignored: continue lines.append(self.fmt.rst_fields(k, self.fmt.sanitize(defi= nition[k]), 0)) @@ -268,6 +293,9 @@ class YnlDocGenerator: lines.append(self.fmt.rst_subsubsection(attr_line)) =20 for k in attr.keys(): + if k =3D=3D LINE_STR: + lines.append(self.fmt.rst_lineno(attr[k])) + continue if k in preprocessed + ignored: continue if k in linkable: @@ -306,6 +334,8 @@ class YnlDocGenerator: lines =3D [] =20 # Main header + lineno =3D obj.get('__lineno__', 0) + lines.append(self.fmt.rst_lineno(lineno)) =20 family =3D obj['name'] =20 @@ -354,7 +384,7 @@ class YnlDocGenerator: def parse_yaml_file(self, filename: str) -> str: """Transform the YAML specified by filename into an RST-formatted = string""" with open(filename, "r", encoding=3D"utf-8") as spec_file: - yaml_data =3D yaml.safe_load(spec_file) - content =3D self.parse_yaml(yaml_data) + numbered_yaml =3D yaml.load(spec_file, Loader=3DNumberedSafeLo= ader) + content =3D self.parse_yaml(numbered_yaml) =20 return content --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 295162DBF5B; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=ODVty495NJMsJet221E4FlF81hCGDjfH8cYGDXzFicAheuYQ1jbaSr+nuUsoo+4NK+k6+X1J2PJszAe7+lsN/DKAkK8xQvlYlHECOYroFTNgaJUVONWX1LIR1zjtQ0JacBQC8jgEcnFHYrCtgnlAXvaBSWN31uDQeEm31gFgYx4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=sLGX0eyqIoRSaJCtRaOhRqFB+mw5FlWjFBG7e4HNq2I=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=L/4UxkMLsTpQ81U0VLlnAXWdQ1ukA52uA5T8OLt//wQ/GSFDn7mHcJahGVaLoFfUGE8QWbVGztCTJq/3fcHm0wz8yvENJhVYrPHzp8DR8rWC8d7ZnbC65BAh/POa/P0gtTtFYLyHpn0oB55708KR/Y+HOqYTEkB9qPqrHEAdmbc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=skrqAHXT; 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="skrqAHXT" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8AEB2C113CF; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=sLGX0eyqIoRSaJCtRaOhRqFB+mw5FlWjFBG7e4HNq2I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=skrqAHXTbHNgSUzyZwiGm2Fupr9l61UiluGGSBvxmKD6r+ld9HPm3T/9gtlevsEN6 XYEIMvCdpCYWMAWMOv/sjIRwyu9+XIVe9F2260gT/2mGyR/T0esmbK6J4BcMZ5l0l9 nZ8L2eoAnaFoL60aFn+A2mj6Rbvj/yYuyxbr3Jp1XTH8PO93Mn8+ghO4bV2Z/gRanl +0LXBRO3gvGxUgV2ZieuJg4JKdANstYjf0aKHJaKQLucOsPDKvOfj09pk7JZQIkrUw Tf9PXDfi1cuumo4aRVBB1PWSa++psvYvq1kEOiJfK8v5YDRCHYbO4UguU2/eZNSjTq WmJIGEttZ5UxA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036VA-3PEz; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Jakub Kicinski , Simon Horman , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 14/15] docs: parser_yaml.py: add support for line numbers from the parser Date: Wed, 18 Jun 2025 13:46:41 +0200 Message-ID: <33fc2894166805b93d4cf652cff9927a54b4f242.1750246291.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.49.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" Instead of printing line numbers from the temp converted ReST file, get them from the original source. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/parser_yaml.py | 12 ++++++++++-- tools/net/ynl/pyynl/lib/doc_generator.py | 16 ++++++++++++---- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/par= ser_yaml.py index 2b2af239a1c2..5360fcfd4fde 100755 --- a/Documentation/sphinx/parser_yaml.py +++ b/Documentation/sphinx/parser_yaml.py @@ -29,6 +29,8 @@ class YamlParser(Parser): =20 netlink_parser =3D YnlDocGenerator() =20 + re_lineno =3D re.compile(r"\.\. LINENO ([0-9]+)$") + def do_parse(self, inputstring, document, msg): """Parse YAML and generate a document tree.""" =20 @@ -38,8 +40,14 @@ class YamlParser(Parser): =20 try: # Parse message with RSTParser - for i, line in enumerate(msg.split('\n')): - result.append(line, document.current_source, i) + lineoffset =3D 0; + for line in msg.split('\n'): + match =3D self.re_lineno.match(line) + if match: + lineoffset =3D int(match.group(1)) + continue + + result.append(line, document.current_source, lineoffset) =20 rst_parser =3D RSTParser() rst_parser.parse('\n'.join(result), document) diff --git a/tools/net/ynl/pyynl/lib/doc_generator.py b/tools/net/ynl/pyynl= /lib/doc_generator.py index a9d8ab6f2639..7f4f98983cdf 100644 --- a/tools/net/ynl/pyynl/lib/doc_generator.py +++ b/tools/net/ynl/pyynl/lib/doc_generator.py @@ -158,9 +158,11 @@ class YnlDocGenerator: def parse_do(self, do_dict: Dict[str, Any], level: int =3D 0) -> str: """Parse 'do' section and return a formatted string""" lines =3D [] + if LINE_STR in do_dict: + lines.append(self.fmt.rst_lineno(do_dict[LINE_STR])) + for key in do_dict.keys(): if key =3D=3D LINE_STR: - lines.append(self.fmt.rst_lineno(do_dict[key])) continue lines.append(self.fmt.rst_paragraph(self.fmt.bold(key), level = + 1)) if key in ['request', 'reply']: @@ -187,13 +189,15 @@ class YnlDocGenerator: lines =3D [] =20 for operation in operations: + if LINE_STR in operation: + lines.append(self.fmt.rst_lineno(operation[LINE_STR])) + lines.append(self.fmt.rst_section(namespace, 'operation', operation["name"])) lines.append(self.fmt.rst_paragraph(operation["doc"]) + "\n") =20 for key in operation.keys(): if key =3D=3D LINE_STR: - lines.append(self.fmt.rst_lineno(operation[key])) continue =20 if key in preprocessed: @@ -253,10 +257,12 @@ class YnlDocGenerator: lines =3D [] =20 for definition in defs: + if LINE_STR in definition: + lines.append(self.fmt.rst_lineno(definition[LINE_STR])) + lines.append(self.fmt.rst_section(namespace, 'definition', def= inition["name"])) for k in definition.keys(): if k =3D=3D LINE_STR: - lines.append(self.fmt.rst_lineno(definition[k])) continue if k in preprocessed + ignored: continue @@ -284,6 +290,9 @@ class YnlDocGenerator: lines.append(self.fmt.rst_section(namespace, 'attribute-set', entry["name"])) for attr in entry["attributes"]: + if LINE_STR in attr: + lines.append(self.fmt.rst_lineno(attr[LINE_STR])) + type_ =3D attr.get("type") attr_line =3D attr["name"] if type_: @@ -294,7 +303,6 @@ class YnlDocGenerator: =20 for k in attr.keys(): if k =3D=3D LINE_STR: - lines.append(self.fmt.rst_lineno(attr[k])) continue if k in preprocessed + ignored: continue --=20 2.49.0 From nobody Thu Oct 9 08:43:03 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 4C2732DE215; Wed, 18 Jun 2025 11:46:52 +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=1750247212; cv=none; b=N2tOJfOvYZbYC/tycSeMMCAJTnhibLZf5QfU12omgyYB1sqEE5cWAku/FnBOx/+DW57Yufl+pTNjl1CZS+fsJxbL6d426brnqdIDvvC0ucUHDMTc2VvBxC7plC8GjvzdW41rhjZNPb+AOdOaN1SaBMKfyOF9gzxPdbeV7Ejfxtk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1750247212; c=relaxed/simple; bh=Eu6NvKMYNdmD8XfJnfUGiXHKuW5qDdQasrskHf5QPZ8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=O/38wzLXqEMtP7TPta0CAsbiXyrzWZ1BgzQV0WWP2BYTlBLDlWSyZJ1gOTJOFE1HtnY4B8iycwFCHJBc7JgmkHyCp2XU3+D39vNidxcCuA7ODUZeeHckN5UJ+pv8a49CUkWPtqU1yL1VhJ1O85rD0L9nW+y5EZDAKz1126vZ6iQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=fjEpijrh; 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="fjEpijrh" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 920EDC116B1; Wed, 18 Jun 2025 11:46:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1750247211; bh=Eu6NvKMYNdmD8XfJnfUGiXHKuW5qDdQasrskHf5QPZ8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fjEpijrhqmBNi8KU6pghGSfrWjrHcK2mBeSSvc2NDXzB7WXtrfLdwY8ITSuZ0SLW4 UOflw5ezusNQkSFMEDNC7Lin8D068h2KUvM9OXhpG6uMfCZKWAwxbd/X8pGTRtUM5f xxSn8zU6tdbY/GvwUziDCZHUxFyIH4YrtSLbpPKCCy8uKkOnoG/71aCc1i5k7ZkjcC 0WyFGvHe9i51p1Y8hXnnh+3hM/uYlsVEQGfw8fkirnoyVe5qxoByk3xrPJp4Q20KK4 Sfr4Sy7eDT/yGeAHl7Y5DOJXXYpsMmct0qoA5o4fy7lMEtttq6T9dimECUthi6IHQV Iuxlo5NIn76lA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uRrFh-000000036VE-3W9N; Wed, 18 Jun 2025 13:46:49 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Donald Hunter" , "Eric Dumazet" , "Ignacio Encinas Rubio" , "Jan Stancek" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paolo Abeni" , "Ruben Wauters" , "Shuah Khan" , Randy Dunlap , joel@joelfernandes.org, linux-kernel-mentees@lists.linux.dev, linux-kernel@vger.kernel.org, lkmm@lists.linux.dev, netdev@vger.kernel.org, peterz@infradead.org, stern@rowland.harvard.edu Subject: [PATCH v6 15/15] docs: sphinx: add a file with the requirements for lowest version Date: Wed, 18 Jun 2025 13:46:42 +0200 Message-ID: X-Mailer: git-send-email 2.49.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" Those days, it is hard to install a virtual env that would build docs with Sphinx 3.4.3, as even python 3.13 is not compatible anymore with it. /usr/bin/python3.9 -m venv sphinx_3.4.3 . sphinx_3.4.3/bin/activate pip install -r Documentation/sphinx/min_requirements.txt Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/sphinx.rst | 15 +++++++++++++++ Documentation/sphinx/min_requirements.txt | 8 ++++++++ 2 files changed, 23 insertions(+) create mode 100644 Documentation/sphinx/min_requirements.txt diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/s= phinx.rst index 5a91df105141..13943eb532ac 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -131,6 +131,21 @@ It supports two optional parameters: ``--no-virtualenv`` Use OS packaging for Sphinx instead of Python virtual environment. =20 +Installing Sphinx Minimal Version +--------------------------------- + +When changing Sphinx build system, it is important to ensure that +the minimal version will still be supported. Nowadays, it is +becoming harder to do that on modern distributions, as it is not +possible to install with Python 3.13 and above. + +The recommended way is to use the lowest supported Python version +as defined at Documentation/process/changes.rst, creating +a venv with it with, and install minimal requirements with:: + + /usr/bin/python3.9 -m venv sphinx_min + . sphinx_min/bin/activate + pip install -r Documentation/sphinx/min_requirements.txt =20 Sphinx Build =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D diff --git a/Documentation/sphinx/min_requirements.txt b/Documentation/sphi= nx/min_requirements.txt new file mode 100644 index 000000000000..89ea36d5798f --- /dev/null +++ b/Documentation/sphinx/min_requirements.txt @@ -0,0 +1,8 @@ +Sphinx=3D=3D3.4.3 +jinja2<3.1 +docutils<0.18 +sphinxcontrib-applehelp=3D=3D1.0.4 +sphinxcontrib-devhelp=3D=3D1.0.2 +sphinxcontrib-htmlhelp=3D=3D2.0.1 +sphinxcontrib-qthelp=3D=3D1.0.3 +sphinxcontrib-serializinghtml=3D=3D1.1.5 --=20 2.49.0