From nobody Fri Oct 10 13:36:38 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 E46842E2EF9; Fri, 13 Jun 2025 11:42:46 +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=1749814967; cv=none; b=qQxKbW4MyBOudKlD3oOc1Kwqa8h05bo5+CyY3cmSow9rBQFTqEfsCFbZjmxhbAikNufvEZeQrfedqGreGBYWlyorrJuvM1gt084+QEgINBgbiMfEXkHsfC0Op7hd9g/oLDIe8JPgo1viyVsP1q8Fh/JMFvJuWwLNq9pKqZ70frU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=8JLj251EiGtS/E11n5n+267zLGC8qyxQhPvEcm7GqEQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rnPzVzmbm3euJ0rbPXHZ24EFKWUHdPjQo2d7E6kW9377/+omdZj/nbH/QnqGHZA5lLe1KSPWW3OySMALiMptso6n6F1JdMaZFMkaVuTB+n61OtW89QLGkRMIR1HFfAsoY+qw9AhzbPW2Bd7Vb4mUp95pQ8K3n1qESdG1fi/hF94= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OfXMsNuE; 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="OfXMsNuE" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 837F1C4CEEF; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=8JLj251EiGtS/E11n5n+267zLGC8qyxQhPvEcm7GqEQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=OfXMsNuEfbnCAzjcLttoSxLxlVO4Utcw7Ac2B8yV5lJf3mxdJbqdPKzxIr+jOG0RB +ZFDmvrKGU8ym8piW7ewVWatTcVX8WY4AfQWu2dsuie2twuVhDu6ItNrgJZ7ScroNq QkgDQ2jvioSIUvGR2cMutxrECJcFk9jDJkl4kWIcFgSnjRZJIRJpQyYvdS/vTrO6mi rlI/ZjpjEy4myyxSLWcSvRiwY93wpNPqfJlkgYcNVoNELH/BOAUaEbkJ8cmk8y5ned Telif6QT+3TUoI4cB6/TWJALYq1maV+ODmux12s3a9d76I3YSWq/TFDUeF1LoY8qBn vKHBDsbTD3vQA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dEl-26aa; Fri, 13 Jun 2025 13:42:44 +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 v3 01/16] tools: ynl_gen_rst.py: create a top-level reference Date: Fri, 13 Jun 2025 13:42:22 +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" 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>` 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, add a netlink- reference to all generated docs. Signed-off-by: Mauro Carvalho Chehab --- tools/net/ynl/pyynl/ynl_gen_rst.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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 Fri Oct 10 13:36:38 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 E461B2DFA24; Fri, 13 Jun 2025 11:42:46 +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=1749814967; cv=none; b=P85aT+uKHWLkGxywclOruY8nd9EMdWBHrIRcLaJqxpGSm+SULiUGuB87jsEe6k12uIYJBrALv6bAQfQY0MrZZt4vgmU/+poBNw5Fes7F6dkHzov4/1Ff1FLLP7RvlDw58wPriXswmLekj+j5GSYqDuKBK1eslSsRPZXEahwEW54= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=5GdVV6A8bXN64ovkNLx7Xdx5aR1iPXnV/yeu24lgmqI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=snIrhZzsuHQf2lzFiQRgoHAwVku6sRoXJiu7ksNdBtK1wx7vqbPNmLKq+NXUOiq6NCwTK3dikg7pxbhh7dwfQfrcB5fikDqVI+k4wvIXdawmjwtV751ibKnN7Wn4V03IHIK5aAIrYi1jWmm23cH7E/ROwDI6NU/zU9tMzMbip8Q= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Hvfx1zoT; 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="Hvfx1zoT" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 80321C4CEE3; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=5GdVV6A8bXN64ovkNLx7Xdx5aR1iPXnV/yeu24lgmqI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Hvfx1zoTJgVDH9YALvSqHtsWCTtE6WoZ5Vz4I2UMgK9303CSrv6NSP9hoSOrWBR9J z+FvtRAanvH/HLjm/ML10M4ttbt3WE4pMi5DFIwW7UVOBGigWs4WiOG9fU63ROANol jAraCh5pqQwgux9r3gQZV3IyVnFaw4JI61vzDx9ehZoBiGUSp4exVaes9BUSMa3JkT 8A7KTbGeeQWqpZ2EN024aHQinn1RxDMGYmZnKp9NGUTZ3XfcZlbJ6AT4e0ngHgJZIo 5s7GLcaymF1jel1+G1d5hoPeAPEc+uyUsPp4gxmtkqwlWyoOWb/1j8xAHz0/wiAlC3 3TqGIriThVcTA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dEp-2MjJ; Fri, 13 Jun 2025 13:42:44 +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 v3 02/16] docs: netlink: netlink-raw.rst: use :ref: instead of :doc: Date: Fri, 13 Jun 2025 13:42:23 +0200 Message-ID: <4d46b08e43e37403afc09412692cb5eb295019b6.1749812870.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" Having :doc: references with relative paths doesn't always work, as it may have troubles when O=3D is used. So, replace them by Sphinx cross-reference tag that are now created by ynl_gen_rst.py. Signed-off-by: Mauro Carvalho Chehab --- Documentation/userspace-api/netlink/netlink-raw.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 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 --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 E45B12D8798; Fri, 13 Jun 2025 11:42:46 +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=1749814967; cv=none; b=elsSeBWzMaSXSxanTYHthDQ5nNjPx6bZL8MmBy32V8papym5mNqGaydmtu1ysb1WYu7PUTymv3lUnHR8/KFz8/YayNN9IggTi2NxGiBpeTJSq10OaHFr7dBHgjW+Y3JvTZty7GUIlkYblltxuORIgN0ngM52pFDM7vNzT7z4EDs= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=nVMNn0VSngYDSLAUJezTR2b19OzJ86I1XkvSWoGjSbY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QRpz+FtuZmlhBQXhZlHlt+B5dGSlsMEvrTKX4wBZ/KTvs1q7ezafuSq0dGEsdvsSB6RNg7G2gcnmZDQhmoGFx3nNQqSAe1BqodvpWYHbbF9t72XE9LjlapFoqi1KbuD36VY21EGymS9tg6rmKuGoj4Eqc1UnmnAm0BA1KOLCAf4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=iseCSxCn; 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="iseCSxCn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8848FC4CEF1; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=nVMNn0VSngYDSLAUJezTR2b19OzJ86I1XkvSWoGjSbY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iseCSxCnlDuhCFoik+zsyW1hS+dvI8LFmQkqNzeKQXrmtIQMqVdQRfDsddXgoFyGr vdFDu1+Fo2rnKsLmGt03+a6EL8sCxiw6FjwZBbb/FDBfqqAcbDHw6srZf/SZ8Wkfc8 LPN8AUDeHtE+zi17SL2y6EdGg6HVaBRO6Iop6dOkdqWAXoRK0wRPKrXWJZwZc23kAY rDOCoFgTa3y2+QeJKmMIWCpv54OXB2bWWTwnax2iQkDt+V1Bi2euQieLaRinw/HHy2 kpAqJBLQmeh3021zP3dVWrMwTk2nszWTzitkMMjWEGOM/MxrGroeTym/RjtM4Bm4iq 4UuKTg1Ygk1dg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dEt-2cmm; Fri, 13 Jun 2025 13:42:44 +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 v3 03/16] docs: netlink: don't ignore generated rst files Date: Fri, 13 Jun 2025 13:42:24 +0200 Message-ID: <1cf12ab4c027cf27decf70a40aafdd0e2f669299.1749812870.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, the build system generates ReST files inside the source directory. This is not a good idea, specially when we have renames, as make clean won't get rid of them. As the first step to address the issue, stop ignoring those files. This way, we can see exactly what has been produced at build time inside $(srctree): Documentation/networking/netlink_spec/conntrack.rst Documentation/networking/netlink_spec/devlink.rst Documentation/networking/netlink_spec/dpll.rst Documentation/networking/netlink_spec/ethtool.rst Documentation/networking/netlink_spec/fou.rst Documentation/networking/netlink_spec/handshake.rst Documentation/networking/netlink_spec/index.rst Documentation/networking/netlink_spec/lockd.rst Documentation/networking/netlink_spec/mptcp_pm.rst Documentation/networking/netlink_spec/net_shaper.rst Documentation/networking/netlink_spec/netdev.rst Documentation/networking/netlink_spec/nfsd.rst Documentation/networking/netlink_spec/nftables.rst Documentation/networking/netlink_spec/nl80211.rst Documentation/networking/netlink_spec/nlctrl.rst Documentation/networking/netlink_spec/ovs_datapath.rst Documentation/networking/netlink_spec/ovs_flow.rst Documentation/networking/netlink_spec/ovs_vport.rst Documentation/networking/netlink_spec/rt_addr.rst Documentation/networking/netlink_spec/rt_link.rst Documentation/networking/netlink_spec/rt_neigh.rst Documentation/networking/netlink_spec/rt_route.rst Documentation/networking/netlink_spec/rt_rule.rst Documentation/networking/netlink_spec/tc.rst Documentation/networking/netlink_spec/tcp_metrics.rst Documentation/networking/netlink_spec/team.rst Signed-off-by: Mauro Carvalho Chehab --- 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 Fri Oct 10 13:36:38 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 00ADA2E2F05; Fri, 13 Jun 2025 11:42:46 +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=1749814967; cv=none; b=BHBlhZdLAN1Jrt1bIPs6UiCjrmKL+2Zcv806fCLZCpXEhyBTYz6vAOocdPGKiYows3setPKOJ4Z5aTuYH6jLPL2RdM9mGFpZjvhn9zCRolgySvIp8JiC7h5KZrIGE0sdaJp2E5yXBOF0ue7rJBVz/NloZvkgElPKRdc72BNx1S4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=zjfj2Tm7h9LKUnhgzAVTuVnT8YUaP6pYYIdRhxmKFAc=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=F50U7d3hmNC3alibNZaSTGvNpJ2TiuYcZdIb67CqwcixGnlIiJOqRqr/x6wcxdGGwTH5MS1SRdEdvOtSl8FXDPvztBtP6zfc5klFROLHvBMB5sFbDT72LIM2tI0CRql9zIgLxexx2pYvChh3cEVCqeHwIZScoXOMqflx/bAFXZU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=gpoN3aAQ; 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="gpoN3aAQ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 8A300C4CEF3; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=zjfj2Tm7h9LKUnhgzAVTuVnT8YUaP6pYYIdRhxmKFAc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gpoN3aAQBV2ZULJqcXnK4xalcRLf9xEM9T0pb+9xRk+3wSTWgxI4raVeQQVJR1I8+ nqimKiDS6X7aSsBXaI+sTDw3ziqyGvbZliB6ZzIoiB/B8fcBj9PNKjKHkjGyr2iQaq LWqXWUwfXp8XJRCL9cmtn3muOX7XfFRzsYz44r2V0TUVlZ6wZsNU97ZlZVQP1OeBTl U8YBmTGqOldmr72ILtiFGxxYXf/PiHCf/3SHTlcRkHGpgOBcFoYeahMKUnXsVLGPqc QjgIQXgswrziRkZlcQFHjX0CdfLdcb1YAlc7jbHXTPBpAApZTGMApsX2asJDdMWED8 n/AqmBYvFRyow== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dEx-2t8j; Fri, 13 Jun 2025 13:42:44 +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 v3 04/16] tools: ynl_gen_rst.py: make the index parser more generic Date: Fri, 13 Jun 2025 13:42:25 +0200 Message-ID: <3fb42a4aa79631d69041f6750dc0d55dd3067162.1749812870.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" It is not a good practice to store build-generated files inside $(srctree), as one may be using O=3D and even have the Kernel on a read-only directory. Change the YAML generation for netlink files to allow it to parse data based on the source or on the object tree. Signed-off-by: Mauro Carvalho Chehab --- tools/net/ynl/pyynl/ynl_gen_rst.py | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index 7bfb8ceeeefc..b1e5acafb998 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -365,6 +365,7 @@ def parse_arguments() -> argparse.Namespace: =20 parser.add_argument("-v", "--verbose", action=3D"store_true") parser.add_argument("-o", "--output", help=3D"Output file name") + parser.add_argument("-d", "--input_dir", help=3D"YAML input directory") =20 # Index and input are mutually exclusive group =3D parser.add_mutually_exclusive_group() @@ -405,11 +406,14 @@ 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) =20 + dir =3D os.path.dirname(filename) + os.makedirs(dir, exist_ok=3DTrue) + with open(filename, "w", encoding=3D"utf-8") as rst_file: rst_file.write(content) =20 =20 -def generate_main_index_rst(output: str) -> None: +def generate_main_index_rst(output: str, index_dir: str) -> None: """Generate the `networking_spec/index` content and write to the file"= "" lines =3D [] =20 @@ -418,12 +422,18 @@ def generate_main_index_rst(output: str) -> None: lines.append(rst_title("Netlink Family Specifications")) lines.append(rst_toctree(1)) =20 - index_dir =3D os.path.dirname(output) - logging.debug("Looking for .rst files in %s", index_dir) + 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(".rst") or filename =3D=3D "index.rst": + if not filename.endswith(ext) or filename =3D=3D index_fname: continue - lines.append(f" {filename.replace('.rst', '')}\n") + base, ext =3D os.path.splitext(filename) + lines.append(f" {base}\n") =20 logging.debug("Writing an index file at %s", output) write_to_rstfile("".join(lines), output) @@ -447,7 +457,7 @@ def main() -> None: =20 if args.index: # Generate the index RST file - generate_main_index_rst(args.output) + generate_main_index_rst(args.output, args.input_dir) =20 =20 if __name__ =3D=3D "__main__": --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 54D742E7F12; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=asDlZp7y3ctWI93wxcR2rB1mMY2dE/b/TVzjKNFDpETEULeGtSwO83t7VDwyNW4pA5cmMUsZfqQZcp4C7o8NcG0H67FYlegxhLrnrz6JTbxp9lK62NjKazQq0NB7SJV19rtK2i53CfBAp+WPmaNfLhPx2aiU6YIw0USTUaj+8Vw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=cha/mIMe25mR2f/nu4En+YRz7qL3BMOeexKVvY2Yu/Y=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=k9siNMB46Bmwg7inAi347t9ZHfzrnQFGNbRXTp1MG4wmQoMtXW7Dnb32Ah/Iw4kUTYI6W8hsSd6tLHxzy+Eq3U2nS3V+hOtWtAnKTx12pKMhkn5k0p+eUJ58bRnq97uw7VKteG6X+ozP7vuJnZ1qilaasy3Mt1sT9TEjnSCdTgc= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QlyrI9d1; 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="QlyrI9d1" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9CBD9C4CEF2; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=cha/mIMe25mR2f/nu4En+YRz7qL3BMOeexKVvY2Yu/Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=QlyrI9d1DeQw6gp8wKknl6LiqLyLhfAo6xemQv66gTbstF5G9Q8TyS5itcJhuZp2c KFhnopqlocMPBuZYOIPyssdW6W4mhaRbPgh9bWV51frCg5NjrbglqkWFpeUtvpINYU 0Z1j+rG0O5TAF1VToW51J48mJUtalPIbeBg4zlbSC7lz713PofFU/Rjnvaa/TUwMi8 9zdeJhFYqEjGs1PhyflLHmwNTE6Mb/BW6Yfenr9dBF3WuTH9TISI3IQqrcv3ETTm6U s8zM8FrFEEwxnbTWFNNbJ0ORTxT47R56t99ByOJaF4tR7wVzNpcS35Kd1kZsdqjbId dTkrzijgt3OjQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dF1-3AMI; Fri, 13 Jun 2025 13:42:44 +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 v3 05/16] tools: ynl_gen_rst.py: Split library from command line tool Date: Fri, 13 Jun 2025 13:42:26 +0200 Message-ID: <440956b08faee14ed22575bea6c7b022666e5402.1749812870.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 --- scripts/lib/netlink_yml_parser.py | 391 +++++++++++++++++++++++++++++ tools/net/ynl/pyynl/ynl_gen_rst.py | 374 +-------------------------- 2 files changed, 401 insertions(+), 364 deletions(-) create mode 100755 scripts/lib/netlink_yml_parser.py diff --git a/scripts/lib/netlink_yml_parser.py b/scripts/lib/netlink_yml_pa= rser.py new file mode 100755 index 000000000000..3c15b578f947 --- /dev/null +++ b/scripts/lib/netlink_yml_parser.py @@ -0,0 +1,391 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# -*- coding: utf-8; mode: python -*- + +""" + Script 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 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 +""" + +from typing import Any, Dict, List +import os.path +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 + + +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 generate_main_index_rst(output: str, index_dir: str) -> str: + """Generate the `networking_spec/index` content and write to the file"= "" + lines =3D [] + + lines.append(rst_header()) + lines.append(rst_label("specs")) + lines.append(rst_title("Netlink Family Specifications")) + lines.append(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") + + return "".join(lines), output diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index b1e5acafb998..38dafe3d9179 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -18,345 +18,17 @@ 3) Main function and small helpers """ =20 -from typing import Any, Dict, List import os.path import sys import argparse import logging -import yaml =20 +LIB_DIR =3D "../../../../scripts/lib" +SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) =20 -SPACE_PER_LEVEL =3D 4 +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) =20 - -# 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 +from netlink_yml_parser import parse_yaml_file, generate_main_index_rst =20 =20 def parse_arguments() -> argparse.Namespace: @@ -393,50 +65,24 @@ 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) =20 - dir =3D os.path.dirname(filename) - os.makedirs(dir, exist_ok=3DTrue) + directory =3D os.path.dirname(filename) + os.makedirs(directory, exist_ok=3DTrue) =20 with open(filename, "w", encoding=3D"utf-8") as rst_file: rst_file.write(content) =20 =20 -def generate_main_index_rst(output: str, index_dir: str) -> None: +def write_index_rst(output: str, index_dir: 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")) - lines.append(rst_title("Netlink Family Specifications")) - lines.append(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") + msg =3D generate_main_index_rst(output, index_dir) =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: @@ -457,7 +103,7 @@ def main() -> None: =20 if args.index: # Generate the index RST file - generate_main_index_rst(args.output, args.input_dir) + write_index_rst(args.output, args.input_dir) =20 =20 if __name__ =3D=3D "__main__": --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 585482E7F16; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=KgV0z/czJoexzsf43izPbVUkzm0Gnagx+rbqDXvLnPCSemUOPhjlAsFXrbcl9culYhqRg9YgtFTJ0oLd1VQ4SPVda7dHcRi4TietBx/HIktw9Jc3uGIUwGuudvhyxnwKu+L7oxcBCrmJILlYuuS5rgQFuTGb1KCC3HBgsmA0o7E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=Y/Yde0TuFKXtGxf0g4GXETCrakpEHJYsPtc1DTYzCDk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=DPcGsohGRurgx21SkF1x175PeCk9VKWPocK5EKEVMIUlA1K7wDFKZmc7rb5QRMX6uyBUnrrLDieYCyqRSuoMZYqi9aG1s8/cOTvHPHG1DEUyzNs9GUnwjFnLagQkbughuXWU/F2AXv3KqnRuv5cnYmXe4xc51frt801poJdwFDg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=dH7UK/py; 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="dH7UK/py" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A3D1EC4CEF7; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=Y/Yde0TuFKXtGxf0g4GXETCrakpEHJYsPtc1DTYzCDk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=dH7UK/py2el1Mgg8B9eRuK0IKZ7NA8w8guko5S7eHgudH4OKM6mMTkpB/xN5946vQ UGdPl2uEhUh/bP11r2iVgImfSTyAeQrhmASLA13eGsS4vjxoNvi9jjUC6FxP5MNUKo vFhF4QKzm81xqUkmuF+K84KuEWja1W5L2sbLKb5LQ3f5Omqe8wh18fv2MfDoAp/GXL f10rkwzmutgSzxKd4T1giIEufzDJt1tn+Te4mZ6hUf7OstLVPMY9vzJVE5GNITyIC1 xijRDMADbrlEdR6wc9YVKGheVs3CLbcz61di2DCSfGsX4mWT6SMkOeU6bINI1AAQtw Rpne3lC2GwjZg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dF5-3R9n; Fri, 13 Jun 2025 13:42:44 +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 v3 06/16] scripts: lib: netlink_yml_parser.py: use classes Date: Fri, 13 Jun 2025 13:42:27 +0200 Message-ID: <08ac4b3457b99037c7ec91d7a2589d4c820fd63a.1749812870.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 importing netlink parser into a Sphinx extension, move all functions and global variables inside two classes: - RstFormatters, containing ReST formatter logic, which are YAML independent; - NetlinkYamlParser: contains the actual parser classes. That's the only class that needs to be imported by the script or by a Sphinx extension. With that, we won't pollute Sphinx namespace, avoiding any potential clashes. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/netlink_yml_parser.py | 592 +++++++++++++++-------------- tools/net/ynl/pyynl/ynl_gen_rst.py | 19 +- 2 files changed, 313 insertions(+), 298 deletions(-) diff --git a/scripts/lib/netlink_yml_parser.py b/scripts/lib/netlink_yml_pa= rser.py index 3c15b578f947..8d7961a1a256 100755 --- a/scripts/lib/netlink_yml_parser.py +++ b/scripts/lib/netlink_yml_parser.py @@ -3,389 +3,407 @@ # -*- coding: utf-8; mode: python -*- =20 """ - Script to auto generate the documentation for Netlink specifications. + Class to auto generate the documentation for Netlink specifications. =20 :copyright: Copyright (C) 2023 Breno Leitao :license: GPL Version 2, June 1991 see linux/COPYING for details. =20 - This script performs extensive parsing to the Linux kernel's netlink Y= AML + 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. =20 - This code is split in three big parts: + This code is split in two classes: 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 """ =20 from typing import Any, Dict, List import os.path +import sys +import argparse import logging import yaml =20 =20 -SPACE_PER_LEVEL =3D 4 - - +# =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 -def headroom(level: int) -> str: - """Return space to format""" - return " " * (level * SPACE_PER_LEVEL) +class RstFormatters: + SPACE_PER_LEVEL =3D 4 =20 + @staticmethod + def headroom(level: int) -> str: + """Return space to format""" + return " " * (level * RstFormatters.SPACE_PER_LEVEL) =20 -def bold(text: str) -> str: - """Format bold text""" - return f"**{text}**" =20 + @staticmethod + def bold(text: str) -> str: + """Format bold text""" + return f"**{text}**" =20 -def inline(text: str) -> str: - """Format inline text""" - return f"``{text}``" =20 + @staticmethod + def inline(text: str) -> str: + """Format inline text""" + return f"``{text}``" =20 -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() =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(key: str, value: str, level: int =3D 0) -> str: - """Return a RST formatted field""" - return headroom(level) + f":{key}: {value}" =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(key: str, value: Any, level: int =3D 0) -> str: - """Format a single rst definition""" - return headroom(level) + key + "\n" + headroom(level + 1) + str(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(paragraph: str, level: int =3D 0) -> str: - """Return a formatted paragraph""" - return headroom(level) + paragraph =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(item: str, level: int =3D 0) -> str: - """Return a formatted a bullet""" - return headroom(level) + f"- {item}" =20 + def rst_bullet(self, item: str, level: int =3D 0) -> str: + """Return a formatted a bullet""" + return self.headroom(level) + f"- {item}" =20 -def rst_subsection(title: str) -> str: - """Add a sub-section to the document""" - return f"{title}\n" + "-" * len(title) =20 + @staticmethod + def rst_subsection(title: str) -> str: + """Add a sub-section to the document""" + return f"{title}\n" + "-" * len(title) =20 -def rst_subsubsection(title: str) -> str: - """Add a sub-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 -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_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 -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_subtitle(title: str) -> str: + """Add a subtitle to the document""" + return "\n" + "-" * len(title) + f"\n{title}\n" + "-" * len(title)= + "\n\n" =20 -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 + @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(list_: List[str], level: int =3D 0) -> str: - """Format a list using inlines""" - return headroom(level) + "[" + ", ".join(inline(i) for i in list_) + "= ]" =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 -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}`" =20 + @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}`" =20 -def rst_header() -> str: - """The headers for all the auto generated RST files""" - lines =3D [] =20 - lines.append(rst_paragraph(".. SPDX-License-Identifier: GPL-2.0")) - lines.append(rst_paragraph(".. NOTE: This document was auto-generated.= \n\n")) + def rst_header(self) -> str: + """The headers for all the auto generated RST files""" + lines =3D [] =20 - return "\n".join(lines) + 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")) =20 + return "\n".join(lines) =20 -def rst_toctree(maxdepth: int =3D 2) -> str: - """Generate a toctree RST primitive""" - lines =3D [] =20 - lines.append(".. toctree::") - lines.append(f" :maxdepth: {maxdepth}\n\n") + @staticmethod + def rst_toctree(maxdepth: int =3D 2) -> str: + """Generate a toctree RST primitive""" + lines =3D [] =20 - return "\n".join(lines) + lines.append(".. toctree::") + lines.append(f" :maxdepth: {maxdepth}\n\n") =20 + return "\n".join(lines) =20 -def rst_label(title: str) -> str: - """Return a formatted label""" - return f".. _{title}:\n\n" =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 NetlinkYamlParser: + + 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)) =20 + lines.append("\n") + return "\n".join(lines) =20 -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)) =20 - # New line after fields - lines.append("\n") + 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 [] =20 - 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(): + 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 - 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(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)) =20 - return "\n".join(lines) + return "\n".join(lines) =20 =20 -def parse_sub_messages(entries: List[Dict[str, Any]], namespace: str) -> s= tr: - """Parse sub-message definitions""" - lines =3D [] + 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 [] =20 - for entry in entries: - lines.append(rst_section(namespace, 'sub-message', entry["name"])) - for fmt in entry["formats"]: - value =3D fmt["value"] + 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_)})" =20 - 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") + 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) =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 [] =20 -def parse_yaml(obj: Dict[str, Any]) -> str: - """Format the whole YAML into a RST string""" - lines =3D [] + # Main header =20 - # Main header + family =3D obj['name'] =20 - family =3D obj['name'] + lines.append(self.fmt.rst_header()) + lines.append(self.fmt.rst_label("netlink-" + family)) =20 - lines.append(rst_header()) - lines.append(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")) =20 - 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(self.fmt.rst_subtitle("Summary")) + lines.append(self.fmt.rst_paragraph(obj["doc"], 0)) =20 - if "doc" in obj: - lines.append(rst_subtitle("Summary")) - lines.append(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)) =20 - # 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(self.fmt.rst_subtitle("Multicast groups")) + lines.append(self.parse_mcast_group(obj["mcast-groups"]["list"= ])) =20 - # 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(self.fmt.rst_subtitle("Definitions")) + lines.append(self.parse_definitions(obj["definitions"], family= )) =20 - # 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(self.fmt.rst_subtitle("Attribute sets")) + lines.append(self.parse_attr_sets(obj["attribute-sets"], famil= y)) =20 - # 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(self.fmt.rst_subtitle("Sub-messages")) + lines.append(self.parse_sub_messages(obj["sub-messages"], fami= ly)) =20 - # 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) =20 - return "\n".join(lines) =20 + # Main functions + # =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =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: + yaml_data =3D yaml.safe_load(spec_file) + content =3D self.parse_yaml(yaml_data) =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 =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 -def generate_main_index_rst(output: str, index_dir: str) -> str: - """Generate the `networking_spec/index` content and write to the file"= "" - 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)) =20 - lines.append(rst_header()) - lines.append(rst_label("specs")) - lines.append(rst_title("Netlink Family Specifications")) - lines.append(rst_toctree(1)) + index_fname =3D os.path.basename(output) + base, ext =3D os.path.splitext(index_fname) =20 - 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) =20 - 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") =20 - 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) =20 - return "".join(lines), 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 38dafe3d9179..257288f707af 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -10,12 +10,7 @@ =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 import os.path @@ -28,7 +23,7 @@ SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) =20 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) =20 -from netlink_yml_parser import parse_yaml_file, generate_main_index_rst +from netlink_yml_parser import NetlinkYamlParser =20 =20 def parse_arguments() -> argparse.Namespace: @@ -76,10 +71,10 @@ def write_to_rstfile(content: str, filename: str) -> No= ne: rst_file.write(content) =20 =20 -def write_index_rst(output: str, index_dir: str) -> None: +def write_index_rst(parser: NetlinkYamlParser, output: str, index_dir: str= ) -> None: """Generate the `networking_spec/index` content and write to the file"= "" =20 - msg =3D generate_main_index_rst(output, index_dir) + msg =3D parser.generate_main_index_rst(output, index_dir) =20 logging.debug("Writing an index file at %s", output) write_to_rstfile(msg, output) @@ -90,10 +85,12 @@ def main() -> None: =20 args =3D parse_arguments() =20 + parser =3D NetlinkYamlParser() + 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) @@ -103,7 +100,7 @@ def main() -> None: =20 if args.index: # Generate the index RST file - write_index_rst(args.output, args.input_dir) + write_index_rst(parser, args.output, args.input_dir) =20 =20 if __name__ =3D=3D "__main__": --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 29C5C2E3367; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=CbonMphlUj1cwEKwLqN/3SdGkUKX2+Hn/wtmzAm2+PwDK0wrRdOErPga9Ka6VXdhviX2CebfvEDViCOhFskNiBB2zYN5oc07L6+L8670AwgyfxKRSOOaP9h7mY1PlYstao5qeWn9QEJmUrVpEM+yYDvl4laLsqNBHXXqPLYVnAk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=Rf32VUtonyL0iZQ1xHiMQTgxmKbimCiZo2NoOWu5xrw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ZEp07LfzaIKUOLzqeCBqLV19fNA79cJJ1wsctazHV6CBJcBLxmC//CfEYEIoPb2l9d0xTRZuNvYEsOrJI9TpOFa10z/pYOOh2XAyjIx4qLhLa/UMfL4+Hzr2EYwp9zcE8wLvpRITlNNEWppQsDtqzMsGViNHkh+djX6YmCxjHAk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RMaQTBic; 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="RMaQTBic" Received: by smtp.kernel.org (Postfix) with ESMTPSA id A428EC4CEF9; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=Rf32VUtonyL0iZQ1xHiMQTgxmKbimCiZo2NoOWu5xrw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RMaQTBic+5JE0FIiL22N2OUWULZGc+gSP+/x/sySaChWMoobcAGvsuWXUC2TusgT5 dR7GFYHUXcSe8R+cFWrQrxORxu8CB3PrX2fdcyJSSLcPAQKpHBW8HGmU9yhJb5iHCd yVXa/MpjU6Tj1qZokB4p+namheErBleBPnHxgU48jRILltgPHJrEtooDfoBdyuVK4C 9rubKh+QhalxPE123lVev7zpjeFyPUnc/HSaz4lMN0bbemUG29pDmlgFHOAXKkXBTN 5qhj9bLszgPDUsHj40fgpFWOKYf+sR3s8f0RgJxIr2K9TcYMMFGQmJ77cSMwY7pCRT HIzBA4OsbfQRg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dF9-3hXJ; Fri, 13 Jun 2025 13:42:44 +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 v3 07/16] tools: ynl_gen_rst.py: do some coding style cleanups Date: Fri, 13 Jun 2025 13:42:28 +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" Do some coding style cleanups to make pylint and flake8 happier. Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/netlink_yml_parser.py | 74 +++++++++++------------------- tools/net/ynl/pyynl/ynl_gen_rst.py | 2 +- 2 files changed, 28 insertions(+), 48 deletions(-) diff --git a/scripts/lib/netlink_yml_parser.py b/scripts/lib/netlink_yml_pa= rser.py index 8d7961a1a256..65981b86875f 100755 --- a/scripts/lib/netlink_yml_parser.py +++ b/scripts/lib/netlink_yml_parser.py @@ -19,16 +19,13 @@ =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 +33,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 +102,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 +114,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 +124,14 @@ 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 NetlinkYamlParser: + """YAML Netlink specs Parser""" =20 fmt =3D RstFormatters() =20 @@ -164,7 +143,6 @@ class NetlinkYamlParser: =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 +155,16 @@ class NetlinkYamlParser: =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 +172,8 @@ class NetlinkYamlParser: 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 +185,8 @@ class NetlinkYamlParser: 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 +200,6 @@ class NetlinkYamlParser: =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 +214,19 @@ class NetlinkYamlParser: 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 +251,6 @@ class NetlinkYamlParser: =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 +259,8 @@ class NetlinkYamlParser: 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 +282,13 @@ class NetlinkYamlParser: =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 +296,14 @@ class NetlinkYamlParser: 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 +326,8 @@ class NetlinkYamlParser: # 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 +351,9 @@ class NetlinkYamlParser: =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 +362,6 @@ class NetlinkYamlParser: =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 [] diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index 257288f707af..317093623dab 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -23,7 +23,7 @@ SRC_DIR =3D os.path.dirname(os.path.realpath(__file__)) =20 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) =20 -from netlink_yml_parser import NetlinkYamlParser +from netlink_yml_parser import NetlinkYamlParser # pylint: disable=3D= C0413 =20 =20 def parse_arguments() -> argparse.Namespace: --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 360A72E336F; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=BrIsL+6prrvjcReQcTj96R7QnDMxsBp4ZQWrozBbVWttCq0lnnLU45KjUcgF8dzDEpcI6XZmprnhQ/waTZSJjvqGGBLN6JjrDCCdbYDi5WAAdxLrv8HdIq3c2Z7ehD9JU+VeyuqjVFGlf7SkgWtYRQKVoMV+AnCPcQRDP4CDN5M= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=FtB7UQx8Rq2PDYZjw/X+61j5J92UiusLvQz1RbjcG2k=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=fxc7Dqjd0yAOsTtw2mosWe3/H45pn+Q8pkNsQt9MyLd9EKlHtxbqAoIdswPqwECZxSzVenRUd3sILKCDK5H2tYdQ1WFuT4G8yu2nArZBv1BNbomec+rCrv2TubmduFBO8VNgv4nEC35SA+lr4AioPasrqr5PvnWLv1O9TGgJW4s= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=AYCGk0vc; 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="AYCGk0vc" Received: by smtp.kernel.org (Postfix) with ESMTPSA id B5154C4CEFA; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=FtB7UQx8Rq2PDYZjw/X+61j5J92UiusLvQz1RbjcG2k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=AYCGk0vcjmA66aO6O0/wOHwZqTgcfAyS/ANPycrV9JLAqfj8on4vxlGq/q/9hPA66 Wy9W4uYObYqEn+F2KWMKbCUGUUB+9k0HbIJH3F/EzHGXAJuTSbAE+gWssBbcGfw/jK NLfLwUgCvZG+wqwnOLXHBDXpwp9jIynbK00O/s8bstvIuHxFjJMCEy26N8d4xh9FZ1 wuVwBHXFafBLOqgS8SANs3cHzCJmmxmVUgfztSG0LdySF8sGHTu5SgqOmy4Zm/38oH 0N4c4Gm5H+2fjE3IpxHCXRHRphJvrL/5fnr91QeyNKXY+8I7OlzU5vS37Pi0RMJzKd I3fyXGuQSOAAQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o0-00000005dFD-3xYU; Fri, 13 Jun 2025 13:42:44 +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 , 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 v3 08/16] scripts: netlink_yml_parser.py: improve index.rst generation Date: Fri, 13 Jun 2025 13:42: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" Handle both .yaml and .rst extensions. This way, one can generate an index file inside the sources with: tools/net/ynl/pyynl/ynl_gen_rst.py -x -v -o Documentation/netlink/specs/i= ndex.rst Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/netlink_yml_parser.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/scripts/lib/netlink_yml_parser.py b/scripts/lib/netlink_yml_pa= rser.py index 65981b86875f..3ba28a9a4338 100755 --- a/scripts/lib/netlink_yml_parser.py +++ b/scripts/lib/netlink_yml_parser.py @@ -372,15 +372,20 @@ class NetlinkYamlParser: lines.append(self.fmt.rst_toctree(1)) =20 index_fname =3D os.path.basename(output) - base, ext =3D os.path.splitext(index_fname) =20 if not index_dir: index_dir =3D os.path.dirname(output) =20 - logging.debug(f"Looking for {ext} files in %s", index_dir) + exts =3D [ ".yaml", ".rst" ] + + logging.debug(f"Looking for files in %s", index_dir) for filename in sorted(os.listdir(index_dir)): - if not filename.endswith(ext) or filename =3D=3D index_fname: + if filename =3D=3D index_fname: continue + + for ext in exts: + if not filename.endswith(ext): + continue base, ext =3D os.path.splitext(filename) lines.append(f" {base}\n") =20 --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 52DB62E7F10; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=NVCu/PmpYLbleC5XAKT1pwAmcjtnPPQn8M63xa7nsS2Ih4pZldCvKTX4hSstbwV62diTJntuwyOTPRc5//WfvYkBftqz2Zface8GeLmA6sueOo6EtbV2uGId85+i/uWmgtzBJPU3RJOty7shPc+reUP66TYzLVCjP5v7X0lt49o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=BNiT6T73vSHdjoYinnCVLRiSA/MjExWs0t2+7SQv6UY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=OgxDqwn/QzWmI1ykI5G62NknJA9KASkxI7/TNcuFXjPqaXY0ek+RQDCKcPF2aeIE7+D5waj5x8Qll0UpioUPB/DQw+okxBp1drmHKUNze0dIk4c9niIQ5Qb09J9+WCNzZivgYc8FPjUb8MR4yzbYwnU3mSaiDk6gYG9ZLYKIVUE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=c3+2XmTX; 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="c3+2XmTX" Received: by smtp.kernel.org (Postfix) with ESMTPSA id BFB42C4CEF5; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=BNiT6T73vSHdjoYinnCVLRiSA/MjExWs0t2+7SQv6UY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=c3+2XmTXCVJ36/pQliRQt0xF7ms+HE7PHLWqU/8HSGglbZH72J4OC6dujS/rtrA+x q7UB0tUQPGe18OoMQdSY8LKqGEa+kG614p4CUiab1uU+RtfDp4vl/PbLunsDEc/fs8 tKjMOh8tLj+de7BN5iHGGQFImFN6HbpWAhWDCORZLQEVTMi2WRFalFdrS4STeRSWbh LRW/xLy5yeqLYPsovewQ/AwURV3e37pDXrvFG3B8gHpx2+pY/kNPKF7W733mzvKh/y xIfXCuL3gqnRx93prBQWwS1c0CUSsax3u8BgAjR4K4c6LpnHawXoCpieyXaYHVBw2c 0TZSwcIA8FUIg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFH-01S4; Fri, 13 Jun 2025 13:42:45 +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 v3 09/16] docs: sphinx: add a parser template for yaml files Date: Fri, 13 Jun 2025 13:42:30 +0200 Message-ID: <39789f17215178892544ffc408a4d0d9f4017f37.1749812870.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 class meant to handle yaml files. For now, it just replaces a yaml file by a simple ReST code. I opted to do this way, as this patch can be used as basis for new file format parsers. We may use this as an example to parse other types of files. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sphinx/parser_yaml.py | 63 +++++++++++++++++++++++++++++ 1 file changed, 63 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..b3cde9cf7aac --- /dev/null +++ b/Documentation/sphinx/parser_yaml.py @@ -0,0 +1,63 @@ +""" +Sphinx extension for processing YAML files +""" + +import os + +from docutils.parsers.rst import Parser as RSTParser +from docutils.statemachine import ViewList + +from sphinx.util import logging +from sphinx.parsers import Parser + +from pprint import pformat + +logger =3D logging.getLogger(__name__) + +class YamlParser(Parser): + """Custom parser for YAML files.""" + + supported =3D ('yaml', 'yml') + + # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser + def parse(self, inputstring, document): + """Parse YAML and generate a document tree.""" + + self.setup_parse(inputstring, document) + + result =3D ViewList() + + try: + # FIXME: Test logic to generate some ReST content + basename =3D os.path.basename(document.current_source) + title =3D os.path.splitext(basename)[0].replace('_', ' ').titl= e() + + msg =3D f"{title}\n" + msg +=3D "=3D" * len(title) + "\n\n" + msg +=3D "Something\n" + + # 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() + +def setup(app): + """Setup function for the Sphinx extension.""" + + # Add YAML parser + app.add_source_parser(YamlParser) + app.add_source_suffix('.yaml', 'yaml') + app.add_source_suffix('.yml', 'yaml') + + return { + 'version': '1.0', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 5339A2E7F11; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=UoRywwoQleQ2e7slaSIqXhZr7YFSHHktmp8jTQSQLnpJFkjI8VtCGXf/ZM44LDn3bSYhtD0S9Wa/JhgmL2a+hMDsPnxWnfRceUJY0+4LNzaJ01vljqd9J6RRtxF36PTboYhg6x4gXhcbJC1fqUAyd5+S4Rtm2lYcfQ/agzye1jw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=RRdlkBDEmtJLl36U7brH9gBLYzEATksRx+v4nftXEzw=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=OYM1h6YwA+J//k0wi6OlRHSbr1j0FoB3GI+lrG0Rp3qyxO11PrEUCybvWE86nE2ngcDcxLZE7ee4jwJF9ErmMZmWsKPjNFBUdkxatbkl5/QVYOlMvOYDrgJU1Vj4S7wS20b5VI89Syw4/M3pvP5Os8ptltso0Oq1JwmvGA2s7O4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZmGIdAIs; 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="ZmGIdAIs" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D376FC4CEFB; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=RRdlkBDEmtJLl36U7brH9gBLYzEATksRx+v4nftXEzw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZmGIdAIsF0j6fvs/aNpGs7XICMloa8BBj4qNnaJyZorcJMurW0D9UgxrAAkTS9/0v 8SyEXLnnRagkMuh8G8DicDy8CXClaNLOu73Qyc25xezUaV7RkEh1k6b4t8KImyj7b7 rkdIKn7Ko2x6qegq3cgYFn02kZ/2PnQoBzY0JWRnwbmjgprHDWxZF8vSdfnjv77LV9 u8z3BPMS1m4YtSMzK5FwscoklNgc+D3VknGw2ud2mNCER6cBdHIjLZTjh2mdMA+4yL oBQedOA7OyLgaUqb0hChwXizST/9aaG/Sa/k0ZNHhzhP3+Ttp2uFd0WYIKLdkW/74p 3WvLkzbJztGkw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFL-0H9X; Fri, 13 Jun 2025 13:42:45 +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 v3 10/16] docs: sphinx: parser_yaml.py: add Netlink specs parser Date: Fri, 13 Jun 2025 13:42:31 +0200 Message-ID: <095fba5224a22b86a7604773ddaf9b5193157bc1.1749812870.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" Place the code at parser_yaml.py to handle Netlink specs. All other yaml files are ignored. Signed-off-by: Mauro Carvalho Chehab --- .pylintrc | 2 +- Documentation/sphinx/parser_yaml.py | 39 +++++++++++++++++++++-------- 2 files changed, 29 insertions(+), 12 deletions(-) diff --git a/.pylintrc b/.pylintrc index 30b8ae1659f8..f1d21379254b 100644 --- a/.pylintrc +++ b/.pylintrc @@ -1,2 +1,2 @@ [MASTER] -init-hook=3D'import sys; sys.path +=3D ["scripts/lib/kdoc", "scripts/lib/a= bi"]' +init-hook=3D'import sys; sys.path +=3D ["scripts/lib", "scripts/lib/kdoc",= "scripts/lib/abi"]' diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/par= ser_yaml.py index b3cde9cf7aac..eb32e3249274 100755 --- a/Documentation/sphinx/parser_yaml.py +++ b/Documentation/sphinx/parser_yaml.py @@ -3,6 +3,10 @@ Sphinx extension for processing YAML files """ =20 import os +import re +import sys + +from pprint import pformat =20 from docutils.parsers.rst import Parser as RSTParser from docutils.statemachine import ViewList @@ -10,7 +14,10 @@ from docutils.statemachine import ViewList from sphinx.util import logging from sphinx.parsers import Parser =20 -from pprint import pformat +srctree =3D os.path.abspath(os.environ["srctree"]) +sys.path.insert(0, os.path.join(srctree, "scripts/lib")) + +from netlink_yml_parser import NetlinkYamlParser # pylint: disable=3D= C0413 =20 logger =3D logging.getLogger(__name__) =20 @@ -19,8 +26,9 @@ class YamlParser(Parser): =20 supported =3D ('yaml', 'yml') =20 - # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser - def parse(self, inputstring, document): + netlink_parser =3D NetlinkYamlParser() + + def do_parse(self, inputstring, document, msg): """Parse YAML and generate a document tree.""" =20 self.setup_parse(inputstring, document) @@ -28,14 +36,6 @@ class YamlParser(Parser): result =3D ViewList() =20 try: - # FIXME: Test logic to generate some ReST content - basename =3D os.path.basename(document.current_source) - title =3D os.path.splitext(basename)[0].replace('_', ' ').titl= e() - - msg =3D f"{title}\n" - msg +=3D "=3D" * len(title) + "\n\n" - msg +=3D "Something\n" - # Parse message with RSTParser for i, line in enumerate(msg.split('\n')): result.append(line, document.current_source, i) @@ -48,6 +48,23 @@ class YamlParser(Parser): =20 self.finish_parse() =20 + # 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 re.search("/netlink/specs/", fname): + if fname.endswith("index.yaml"): + msg =3D self.netlink_parser.generate_main_index_rst(fname,= None) + else: + 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.""" =20 --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 515042E7F0E; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=AxFUYCCynBo46xf/5JQaw8tOb8MZqlFW4u59VeNu89ssSBvILV9RAcv8/DrF5+Kl1XSxcIlyS2ZhZ57ysLfWkgAg0ysscGU9UeWmOyv0iTCKcbAmio86S+HT1jFyVJdfOyLu/ixj0GDI3niTaFo844iW+nHIKC/qYsN4jr4GjQ4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=YBkjGXm+GCy8o/xx1o50ol5uO7XCwqyBr79mwHQ/z4o=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=F/NLc+ox9zW5/e65YRhe98XGdHhN/tmbS1UueCq3/l+pMLQjVSnKFngI+nrjyWg1XO+f0feXGcS3y5xN6RyPix5jcE8abW6iA89ODSZFOdgRGBSRoxAUSLJxnFd64GlQkrRbxCWzzvDrZSxd9qxBOEov2v3gNe8rAJWnR97W1r0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Gy3mxKtn; 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="Gy3mxKtn" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DD90DC4CEFC; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814966; bh=YBkjGXm+GCy8o/xx1o50ol5uO7XCwqyBr79mwHQ/z4o=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Gy3mxKtnerMdNmaAfxLjcCdYev3j4LJ4Ma6S4xmXIuYZOG5rTcqSp0P2bRHTcy7p3 Q9XbPn9aViuqPD94eHh5mePfrxKwfdO7i1SHNE9dNOkIH+Vui3LO7z8csPWQqnIkhm dBzRPx2+UYNo/UsfKSPD6YnB40Xu2cuBZfAnko6dOv/IC/ydzWYY/NNUWLBzIUJ2YD D+rn48dAvUPrssNOtTYiC5OfHMtzPvyVATuWmTz6n7Arh6x4Jz54HMIw7GZ073lPpL bjRdJpknjpciPMeJ5Trr37i0QpZNlbMzlA+vgsC3X6qXhowmDSdOm1kBJn4vqIYxMU 0jS65AuRqEnEA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFP-0XeS; Fri, 13 Jun 2025 13:42:45 +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 v3 11/16] docs: use parser_yaml extension to handle Netlink specs Date: Fri, 13 Jun 2025 13:42:32 +0200 Message-ID: <931e46a6fdda4fa67df731b052c121b9094fbd8a.1749812870.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. Signed-off-by: Mauro Carvalho Chehab --- Documentation/Makefile | 17 --------- Documentation/conf.py | 11 +++--- Documentation/netlink/specs/index.rst | 38 +++++++++++++++++++ Documentation/networking/index.rst | 2 +- .../networking/netlink_spec/readme.txt | 4 -- Documentation/sphinx/parser_yaml.py | 2 +- 6 files changed, 46 insertions(+), 28 deletions(-) create mode 100644 Documentation/netlink/specs/index.rst delete mode 100644 Documentation/networking/netlink_spec/readme.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index d30d66ddf1ad..9185680b1e86 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -102,22 +102,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))) @@ -184,7 +168,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 12de52a2b17e..add6ce78dd80 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -45,7 +45,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. @@ -143,10 +143,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/netlink/specs/index.rst b/Documentation/netlink/= specs/index.rst new file mode 100644 index 000000000000..ca0bf816dc3f --- /dev/null +++ b/Documentation/netlink/specs/index.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. NOTE: This document was auto-generated. + +.. _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 + + conntrack + devlink + dpll + ethtool + fou + handshake + lockd + mptcp_pm + net_shaper + netdev + nfsd + nftables + nl80211 + nlctrl + ovpn + ovs_datapath + ovs_flow + ovs_vport + rt-addr + rt-link + rt-neigh + rt-route + rt-rule + tc + tcp_metrics + team 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 eb32e3249274..cdcafe5b3937 100755 --- a/Documentation/sphinx/parser_yaml.py +++ b/Documentation/sphinx/parser_yaml.py @@ -55,7 +55,7 @@ class YamlParser(Parser): fname =3D document.current_source =20 # Handle netlink yaml specs - if re.search("/netlink/specs/", fname): + if re.search("netlink/specs/", fname): if fname.endswith("index.yaml"): msg =3D self.netlink_parser.generate_main_index_rst(fname,= None) else: --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 568A72E7F14; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=fO3nZWvGSq5HIX95sL4CyzaCKJzH9bBowMnXrkD133D3GswI3ukNXfalAwKXpIIAk8hbDXVe4D2Nqbsq6i1fa4W/Mc2QwREPK+2TxKHB14Mk1FtcXkKomiUlZIbC5sWVDrwAeBTIXb25BS5lfg/5uENlskpFBJyzjdJcTkSsqYI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=FsS6lOMAqt6O4kSiWFDk/a19S4XMRpll04UTzLeJcwU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=m1Ri9Er824UnFP8PwBSBWv/wCVJ6JGw66OyJtDZ4EwuHz+IO5crhHGLqiyCBDGigSyAhBCuzchGX7xw9WGYSf3Hq9/xj81J7EUX7TNJQUCMNFMdWIqnCYpnkxN025z8LOlm0Sa4Xd6coK3WMMCayzyfWv9RZ6azSgV3/z2n5Uos= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=sOWEBoJZ; 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="sOWEBoJZ" Received: by smtp.kernel.org (Postfix) with ESMTPSA id F05C7C4CEF4; Fri, 13 Jun 2025 11:42:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=FsS6lOMAqt6O4kSiWFDk/a19S4XMRpll04UTzLeJcwU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sOWEBoJZ4vIFTsylM2WbefCfKVG/jZ9zBR7K4NKzUvNInZxR4/2AQ6bRJMbqrITo8 bcSDxDthQft49+QvovfnkDU4DbL0DKwBzoo06vee/WU60tAqCB8OZK2xWgze6nOAzo RkguEgrgh1CBZKcr9zVVt1Tb6ewbQ+Xups5Q7+ihBapQNEo/pyICfppBZ5Rjv73xsH 6KCCbsLQIi9B5XeAJqPsJ4JEDtjXoge/CmB+O7m2lifCkUsLNf0c+mIb3BfXuy9/rF E8ztchjxy1pEf5jgIknUm/jYth6oBu43XmterWANGYoA8u+sfCH3aWml0b0+D5TEpY T9GUN4lwR6Lpw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFS-0n5d; Fri, 13 Jun 2025 13:42:45 +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 v3 12/16] docs: conf.py: don't handle yaml files outside Netlink specs Date: Fri, 13 Jun 2025 13:42:33 +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-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab The parser_yaml extension already has a logic to prevent handing all yaml documents. However, if we don't also exclude the patterns at conf.py, the build time would increase a lot, and warnings like those would be generated: Documentation/netlink/genetlink.yaml: WARNING: o documento n=C3=A3o est= =C3=A1 inclu=C3=ADdo em nenhum toctree Documentation/netlink/genetlink-c.yaml: WARNING: o documento n=C3=A3o e= st=C3=A1 inclu=C3=ADdo em nenhum toctree Documentation/netlink/genetlink-legacy.yaml: WARNING: o documento n=C3= =A3o est=C3=A1 inclu=C3=ADdo em nenhum toctree Documentation/netlink/index.rst: WARNING: o documento n=C3=A3o est=C3= =A1 inclu=C3=ADdo em nenhum toctree Documentation/netlink/netlink-raw.yaml: WARNING: o documento n=C3=A3o e= st=C3=A1 inclu=C3=ADdo em nenhum toctree Add some exclusion rules to prevent that. Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index add6ce78dd80..b8668bcaf090 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -222,7 +222,11 @@ language =3D 'en' =20 # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns =3D ['output'] +exclude_patterns =3D [ + 'output', + 'devicetree/bindings/**.yaml', + 'netlink/*.yaml', +] =20 # The reST default role (used for this markup: `text`) to use for all # documents. --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 56E1B2E7F15; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=PyuXZDN2dsAU4GBnW3HgmNx4wc6jsSqSLlLf5zy5tHK/otDywnwlQNAq4NSh2op9lL4jh0cOCmjg7RDUEFxZqdbzHfCLENzJbm3W1itIuQsYbB9m2Te6zbrERtYHNWJ9iEpsVcnrs+FIcbEi2lOUmFVP/GWRwLWqblPD6KDUZhM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=1pNBoqfcOumx5Zb6O8muZgcXFYZBfhHDEKXQatZBLVg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=NDzonkdX/wI20gqpIE6lqm47p45VYD3stOd4qN1F8smO4e8JugXfUVa0ExdIGRaMqXssOvTk1bJkTHVEqIyotw+FHRNLl48Gn3EGOnY6wH6aiI2JzzDIVVAdaj0mbNxoy7EGNZddRfKWi4EUPQ6xdcMJPB35QpDpvoExyPv38sY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=FC+qX+iL; 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="FC+qX+iL" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 086C4C113D0; Fri, 13 Jun 2025 11:42:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=1pNBoqfcOumx5Zb6O8muZgcXFYZBfhHDEKXQatZBLVg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FC+qX+iL8AD9wg7+jylIRsZLBYdwYXs+4AbkRTRw+RHA5jGUj5/2wDleAzz6MHvKZ QeP+/t5JVs7hC8HtcwFpRvSKyJMkcJcvPnAMlXW4t9NtfNCAQYyIzFQ1tPHJOc9Hpv neWJl1nHlYBwZ0e+3x1oVIMKY5dthSmYXvXXKGV9Sae9WYsjTaGwFvt7NOuPlnAfpZ G3ktyUHa+BCB0E34FEDN2j2YeatfKLl5SFVfotpxGJEHQOsnwoVkoMBv/oWl2b4gi/ lI+AJo/WQaAvNeg1sO/4xIBSOFW4Vao/kL9YP6RySnq1gHYGQP3UdbWH32zo3VJqF3 7FXSaBUi0HJug== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFX-13RQ; Fri, 13 Jun 2025 13:42:45 +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 v3 13/16] docs: conf.py: add include_pattern to speedup Date: Fri, 13 Jun 2025 13:42:34 +0200 Message-ID: <62f2de3a195dc47ba6919721e460a8dd7ae95bc3.1749812870.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" Now that we have a parser for yaml, use include_pattern, adding just yaml files from the only directory we currently process. Signed-off-by: Mauro Carvalho Chehab --- Documentation/conf.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index b8668bcaf090..60e6998e49e1 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -222,10 +222,13 @@ language =3D 'en' =20 # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. +include_patterns =3D [ + '**.rst', + 'netlink/specs/*.yaml', +] + exclude_patterns =3D [ 'output', - 'devicetree/bindings/**.yaml', - 'netlink/*.yaml', ] =20 # The reST default role (used for this markup: `text`) to use for all --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 515B62E7F0F; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=rbMuC7LKECJq31ONP5gDUveeHAYqys4lcjHO2xkXm0oozI0LSWI8h8tSkggwFpXe0/i0/EP1vguOUke0pyLnBZ9V9260nyceKvs+99ys1we6vR4KyooM8QcIEwJgXMc69lq4EX6GYfU5jTx62OeD3YGsmrxSbFM1IbXkLfGiJx0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=00F9KG3FuikbC/77I/aVEWzxRtC/68GGYQsrs3gqu00=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=laln4MRMV3hGNvcdyRR90Zr1Sz6NYjr8dxhl1oO2iekxO3YaijWVkxp6kyZwo5skzmJ/UyPR6+4Hfqmv2TvkvI6eJaV6sPbskPef4X80aq0CJsyfWytrHQ8sGJnt7rlRsO0E7iTye6+xwLv9wheSefLyL5EW7I5XH0I2XPl5XOo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=n8V4C1BO; 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="n8V4C1BO" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 14BC6C4CEF6; Fri, 13 Jun 2025 11:42:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=00F9KG3FuikbC/77I/aVEWzxRtC/68GGYQsrs3gqu00=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=n8V4C1BOOz9J6Zod51ygicZmxKyH3Khf5Pv8hbZKDvaB/EvM123i+8YFtOHvuJkln cPbUTMlosX01zhHV3VN9ISky9oGSo8FAE62NPWmUZMDwTA40CvZ1nC6mtObLgSWKJt Jx0Bce5fy+UtAwKfTfTkkdsk06+k5YCQDzyu/dMh40yRCCf664Lo5rOI+gFQJiwEp/ HsIZXRYx68TN08DlVOJXC2lyEPmpvvmuhp1heCKw1HMsEns6pH9zWEO1l+/PF0hMXz 5sBAvIbmWx8sYZRezi6GGoO49S93GE0mlMBJuvkeY8MrKPUtCGSYn4qbyn377f/Lz2 xkhMs1f0sz6wg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFb-1IEG; Fri, 13 Jun 2025 13:42:45 +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 v3 14/16] docs: uapi: netlink: update netlink specs link Date: Fri, 13 Jun 2025 13:42:35 +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" 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 --- 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 Fri Oct 10 13:36:38 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 8972C2E7F36; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=oQ8D+JwpeBJcbdURAx888kmdrAOfEwZLyDC7mw7RE+eDaCPzJcO4/r74dc2ycDXwv6paiYdJcztiG081Cjb0fCWvnc23X/0u3bhW8iT1b+gSjn1iVRRPiyyBrRDAKjFgzs2GXbOpXAw9yV9Y6kvIsrf+ztIStWLeibk+zGxTi/I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=qdx5eLFhJs3mwB2br6zWhdyUu0aQq9T5BmAjQqI3pSk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=BCMOihGies2BUU/SdMqFvtqxEoLnt0rQ5yP/Sol9G9c3vPVat4MLgi+Oasftj1+DNRiJHJfvPuA1HtDyYvmjBfdjPV+fILFUYydnWJq7hagQwJBVMmpURmrqZPxAQhRrZkI5IUGIGFd+FCcBpaAcdalobttGqwX1ERcngIFL9bY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=tMFGL2LM; 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="tMFGL2LM" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 1EA28C4CEE3; Fri, 13 Jun 2025 11:42:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=qdx5eLFhJs3mwB2br6zWhdyUu0aQq9T5BmAjQqI3pSk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tMFGL2LMp6jcV5y3OjWE1cneuwdj/V41scMM0iuDv5YGDEbEw0TEbmpgLm9ihPPzr QuL3oTW6HiBiU5Gn8A17+/gDWwFj/1+uSGc3N/NfMvuWht2VkizyXieWpsFwULRlLM 13Z+fTR4+4L1BEuQHrU4uVhCw1C4Ly3r4nXB97r1O+y7HzI7zjc3Xw0jxXC5cPYUS1 wpUuSmYwJXIm5Tn1aA2B5RC1DFJV1GaPh3e9TaRpyJz2gIH7eQKCnKDXAVRvG8bIYC Tzbq/0ymJ6REa32YPq+ItHq2iA6hec4XPG3ZPYDJ00hRRE0OWyuSHtXD0HMvt1uuot pfzocEgnH4FQg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFe-1WGD; Fri, 13 Jun 2025 13:42:45 +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 v3 15/16] MAINTAINERS: add maintainers for netlink_yml_parser.py Date: Fri, 13 Jun 2025 13:42:36 +0200 Message-ID: <6de10a419ab9740030f9508e6e913639953cc656.1749812870.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 parsing code from tools/net/ynl/pyynl/ynl_gen_rst.py was moved to scripts/lib/netlink_yml_parser.py. Its maintainership is done by Netlink maintainers. Yet, as it is used by Sphinx build system, add it also to linux-doc maintainers, as changes there might affect documentation builds. So, linux-docs ML should ideally be C/C on changes to it. Signed-off-by: Mauro Carvalho Chehab --- MAINTAINERS | 2 ++ 1 file changed, 2 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index a92290fffa16..2c0b13e5d8fc 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: scripts/lib/netlink_yml_parser.py F: scripts/sphinx-pre-install X: Documentation/ABI/ X: Documentation/admin-guide/media/ @@ -27314,6 +27315,7 @@ M: Jakub Kicinski F: Documentation/netlink/ F: Documentation/userspace-api/netlink/intro-specs.rst F: Documentation/userspace-api/netlink/specs.rst +F: scripts/lib/netlink_yml_parser.py F: tools/net/ynl/ =20 YEALINK PHONE DRIVER --=20 2.49.0 From nobody Fri Oct 10 13:36:38 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 5BC412E7F17; Fri, 13 Jun 2025 11:42:47 +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=1749814967; cv=none; b=ATowjSd7MGeaQ6mA7D12tKGv6kPgNkmKbumDIqJdc+4rAKyRMJyJaxORq+ggbLB1KdRZkD5QFuwSoxmz/UVuI943aOoSvYbu4yw5dXlbRH85XFSjAR+pQiwI15juoghKdgAnKG7fipaasvdBWDRo6tKh7vKJ1Z8xjRLUDQXzYDc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749814967; c=relaxed/simple; bh=jazvmyYFMnGYOxxVZMEBOjTd9mMz+TrushWEPpOXIDU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=O4F31+cNvfKmlw62gFu34Rlu+wkYxz5vJIFlBDZx+6FnnkUHdIYmltDqUa38SUT5m/nBu3Yd+0Z6hikJS8hCquruXJh7oAvfg9saK5do4I6e41TPyFnmQgezVGFPUWEzVvmqTc0B0hjpRFyYGOpz9CIJ+v8iAyu9HThtB/GuygY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=BCZ5OEll; 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="BCZ5OEll" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 32BEFC4CEF0; Fri, 13 Jun 2025 11:42:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749814967; bh=jazvmyYFMnGYOxxVZMEBOjTd9mMz+TrushWEPpOXIDU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BCZ5OEll50G95vHVAMlJ4oAHPBCfNFX3WUcZFFup++oyru4a1NoZa4Sq8j+h/KvWG YH2FBzmyxbYLNcA8LxeeCh52QyoUbXXjnfi7rbg+ur7NCwctf2WkRzCmzDeS63mF+E OGbcHd0lKDPspvm7fW+FUxEPHz4NgkjD4VDEXDDCRVI1uN+8YUvIHE9DQONsF80N5p XOS2jR0pCwppCQAoR4A0q18cd1hr77zSnQ8vRH/YoxTsiqeVHI+ea9ROobCLPk8BiV lytCcoR9GaSCr0SDEu7nEBuqodSoQE8te0qJSL22O0U+7TepL1MCf10RNEAeu5gs0d 3Ru45k/lEE3mg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uQ2o1-00000005dFj-1lXM; Fri, 13 Jun 2025 13:42:45 +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 v3 16/16] docs: Makefile: disable check rules on make cleandocs Date: Fri, 13 Jun 2025 13:42:37 +0200 Message-ID: <18a6c2c8a9f331b3d1abc6e943d0e5aa2bc18655.1749812870.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" It doesn't make sense to check for missing ABI and documents when cleaning the tree. Signed-off-by: Mauro Carvalho Chehab --- Documentation/Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Documentation/Makefile b/Documentation/Makefile index 9185680b1e86..820f07e0afe6 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