From nobody Sat Oct 11 12:11:47 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 260171A2564; Tue, 10 Jun 2025 10:46:24 +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=1749552385; cv=none; b=WPFox42xc0jgjY+DtE6vGnXv1kimu3Qg60FKDD8xxzFo8sf7vmz9f2iq9s4DsG6HJogpBrXL+k6wmju1d6lWt+l7PG7UNKYE3OgcUhszB/Yf9B+QB2kqOSwIi2FXRorgnWWaDGOmLc1+7VLXmDupNrETUybixyxeSvRbvBqwtm4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749552385; c=relaxed/simple; bh=8JLj251EiGtS/E11n5n+267zLGC8qyxQhPvEcm7GqEQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=e+lykUmpq9UiSEUrGMikPiLk6sHJsYxiSyGD8YqGsx2BbQRgpCNI+DLfHKjvEmGvhNbVNmf1KHCbpjtAVC0X6vYYQZCPEeaIVekjefHStD2Ljn5VLCm+cHL1o2DUUKVZjErMJIxKlcElB/L9YubAY3coQFicLlIbRR4k81QA0Fw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RwsLZMRM; 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="RwsLZMRM" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C1D61C4CEED; Tue, 10 Jun 2025 10:46:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749552384; bh=8JLj251EiGtS/E11n5n+267zLGC8qyxQhPvEcm7GqEQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RwsLZMRMGrOKfxc83+DsbyVjsXXIaMTQmxXly3qq612w3OgHSNQ+rW6FqT6NIryTT JGohFd50AnEprkna77PPHqIzZLVFxMlNlJlOmHXNznLJx7hwPx7Dn9El99lPJURmrk wCWQRvVXmfIsPUJ8PeFePt36X8F+NBmgFB38O633c8dCC2wMIBbcnhkVQqi4Vwarzs YHmxLGUQI5gsRMvQ95qTDVoOqOv04PleljZksChmpq4e8ohEvyhiSBstW+FQ8ti+l8 lMM3x8UGK7cxcrf8sBUWhftIEH9znV7Gxed/2FXe4CJPcwYSYR0IrkhJRs4jQnGpOM pWtbbiVoQ04Qg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uOwUo-00000003juv-3izT; Tue, 10 Jun 2025 12:46:22 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Ignacio Encinas Rubio" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paul E. McKenney" , "Shuah Khan" , Donald Hunter , Eric Dumazet , Jakub Kicinski , Jan Stancek , Paolo Abeni , Ruben Wauters , 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 1/4] tools: ynl_gen_rst.py: create a top-level reference Date: Tue, 10 Jun 2025 12:46:04 +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 Sat Oct 11 12:11:47 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 25F7311712; Tue, 10 Jun 2025 10:46:24 +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=1749552385; cv=none; b=EL0krxslYZEYy32J2h7VXrzde3BFh2aJKB2cRyMHStB+8AfkdmS+rf31+ORS2ZJarFkZYvJrqdxDDsX0bcik1peYqs1IrA/4vKw+nYcLxBpcs2srf+87S+oHR2Te8YPwkQ71dGDDIZULwD49AXqVh5AiZVfVwkwwDR9KDreMXsk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749552385; c=relaxed/simple; bh=5GdVV6A8bXN64ovkNLx7Xdx5aR1iPXnV/yeu24lgmqI=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=bVKqEC26toGLwK5xo48zJxoRcox+PEW2avpcE6l8GO/bBV9XZdtsa2f0t7/mggCamoJsUycQKuG8HtYP8TynRQiSuFAMAD4zZxX27cgeEfzH556DG3++KWMoAFQbyqxooBFBtB61ia24ow/eTVbOCNbYU2KirgIF3WU0GLqIKBA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=TdnqWVGe; 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="TdnqWVGe" Received: by smtp.kernel.org (Postfix) with ESMTPSA id C210BC4CEEF; Tue, 10 Jun 2025 10:46:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749552384; bh=5GdVV6A8bXN64ovkNLx7Xdx5aR1iPXnV/yeu24lgmqI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=TdnqWVGevQtmr0KsXTjTfpno1skOkSyi6x1Hks2h6YU0aHrGAguVpDfqBw2W1Q+Dj pIwBi9urXY01/F2pNNKYPsAs6iXfGvQR1H8kedKiHSq0378ycI13RSNn3SoNfVGYzf VCiRrugcypTsecgqpY8zyacuw3Fuhl5+v80KHjmgTBqM2f5OTuwEAKaOgQZ36MEooC PeNvtcVrh2yeDZAZvHTXOb1Eh+sjtl1OVs5yq8GkZe/W6SmBfbYgFqAymWN97oGwtR 3Lj6pPBc+nJcBme5YiLQ6RYTHdETipHqTPqtOMlunrndis24GFiiX/L9FtoPhwg5Bu EVB87LfQOt8CQ== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uOwUo-00000003juz-3zyW; Tue, 10 Jun 2025 12:46:22 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Ignacio Encinas Rubio" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paul E. McKenney" , "Shuah Khan" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , 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 2/4] docs: netlink: netlink-raw.rst: use :ref: instead of :doc: Date: Tue, 10 Jun 2025 12:46:05 +0200 Message-ID: <4d46b08e43e37403afc09412692cb5eb295019b6.1749551140.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 Sat Oct 11 12:11:47 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 3CC5C1E1C1A; Tue, 10 Jun 2025 10:46:25 +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=1749552385; cv=none; b=HkfYoWNTbx+fZ6AuOrCeirLl6L63IdzUolDTF1Jc7hmkcF52v3ajj4bGgGDaeM8cCynqxB8LwA+hB5NOeCS3JpoQGx7A5Sy9950O8IVyS1TM/XZ5Xk93UkfSpAOBx6ez/qs/eXljzGLqNh5IyRKvCxgNuTnR1NeQvddxq+yn/hA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749552385; c=relaxed/simple; bh=nVMNn0VSngYDSLAUJezTR2b19OzJ86I1XkvSWoGjSbY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=QoMFn5/ElIKExVSYzS36dU7uj0TZ/RvHCYeF2/12Hoy29i5Mj9eSgdCg7Uak5tQtrmgisy1AZNjtYwSulK7UmqB/KRf1OJ0CLLbhWdI6n8P/celEpCvF8u6mieC+17Gl4zAMp9S6WHIix1lBEiEDxWb4X1bwRgRDSx3YaiQ/VNE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=a2mM573p; 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="a2mM573p" Received: by smtp.kernel.org (Postfix) with ESMTPSA id D07F6C4CEF2; Tue, 10 Jun 2025 10:46:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749552384; bh=nVMNn0VSngYDSLAUJezTR2b19OzJ86I1XkvSWoGjSbY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=a2mM573px73KHRx8sQXqbhIdJNRe3oVbZRNBz1N6TgLaGiBmkS+HVTR/Fyo2PHoe/ d6tY/TxNxbqFFMvtIJyhiCbvPOdticz3ELLdebqIiCN/CtcGEaa2zNC+aZ0KL1dB0a FrrjQUcTRXx8lpUsI558zi0aQzpFN8EZn7o7dypOWNmtg9GSwXsXeCE305o4BRxCxg K9ecy+bgD2pRQmx2DItTKQo/DebZ1zYFlhBnjz6LHtCbuhoJ5AsbIZyX8u6EqnPtl3 baq4cYqlgMohXdrnoXjr0eiBTGsJl8zObShPZR2Q2Er/nIqz6zEWEbnI/prDTKIDsO EfgLcC0fURJeA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uOwUp-00000003jv3-04QX; Tue, 10 Jun 2025 12:46:23 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Ignacio Encinas Rubio" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paul E. McKenney" , "Shuah Khan" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , 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 3/4] docs: netlink: don't ignore generated rst files Date: Tue, 10 Jun 2025 12:46:06 +0200 Message-ID: <1cf12ab4c027cf27decf70a40aafdd0e2f669299.1749551140.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 Sat Oct 11 12:11:47 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 97F2528D83B; Tue, 10 Jun 2025 10:46:25 +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=1749552385; cv=none; b=qEThMWV6BjjTrQ4HE6JU2cEh1QOMNWb6zmMlqNo6NdaEAUP7SHjG2eSY5FP3XFQaUmtMLXO2rAbV6lOKv7Zo2U9awL5qPKvrjGGfWtZj764gG8itiggvqOOYxFaPs0HVp/lszjTasqkoQX1zDjDOkYD0gXJTpZlIu+ht+nlYAt0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1749552385; c=relaxed/simple; bh=DqGnZHFQp8okuryYab7hQcwECvzwCl4MaxLyGwcrIQ0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hhfmK7s5ZSnlteklA+q+vaTR8NWidBYU9ZraU5xaX8U/DpAl9aFtC7MEFgh5p1i6N9HvhoJxa9gNOEA9tAbXjgbRCO2miyZS7o1c+uMNogjJj5FvfSD7szRCT8LUpaNEyXOtXpIZIopoNSNrHaL+jq6tFADIkwVOsYKojBOXwWw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=oPJ8WUKu; 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="oPJ8WUKu" Received: by smtp.kernel.org (Postfix) with ESMTPSA id DF638C4CEF3; Tue, 10 Jun 2025 10:46:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1749552385; bh=DqGnZHFQp8okuryYab7hQcwECvzwCl4MaxLyGwcrIQ0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oPJ8WUKukYWFWmWP9QnaP5c5AQPTfVT2OANISbaIUy6pmbh53JNPUpK1VBLjARB8o naKBZ1l6iN1lL2/yd0DwZ3OezOcI2zCiaIllnqSmPsQbSuPSgOEcplMaJAPXYr006X 4cesXZ2qpsOMhOEYtVJjhGETR8HFHddJrcA3AfDGiEyCOLcd9BLrLuOcT6WGNgC87X /MxsPn78Drj9fapsaTbGtV42lM4K+OVSRBWFr4vzU6MSXjUsq/ln0TIH0MI8+s6Gag IdnQ10MItiGwQwh34NDOlM9MTKbWhAx1PnK2QEJSyYNPXl3qykghtshJpJqi/ALwFU QdZ7BLaL0RRTw== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uOwUp-00000003jv7-0NSM; Tue, 10 Jun 2025 12:46:23 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , "Jonathan Corbet" Cc: Mauro Carvalho Chehab , "Akira Yokosawa" , "Breno Leitao" , "David S. Miller" , "Ignacio Encinas Rubio" , "Marco Elver" , "Mauro Carvalho Chehab" , "Paul E. McKenney" , "Shuah Khan" , Donald Hunter , Eric Dumazet , Jakub Kicinski , Jan Stancek , Paolo Abeni , Ruben Wauters , 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 4/4] docs: netlink: store generated .rst files at Documentation/output Date: Tue, 10 Jun 2025 12:46:07 +0200 Message-ID: <5183ad8aacc1a56e2dce9cc125b62905b93e83ca.1749551140.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 be inside the documentation output directory. This solution is not perfect, though, as sphinx-build only produces html files only for files inside the source tree. As it is desired to have one netlink file per family, it means that one template file is required for every file inside Documentation/netlink/specs. Such template files are simple enough. All they need is: # Template for Documentation/netlink/specs/.yaml .. kernel-include:: $BUILDDIR/networking/netlink_spec/.rst A better long term solution is to have an extension at Documentation/sphinx that parses *.yaml files for netlink files, which could internally be calling ynl_gen_rst.py. Yet, some care needs to be taken, as yaml extensions are also used inside device tree. Signed-off-by: Mauro Carvalho Chehab --- Documentation/Makefile | 8 ++++---- .../networking/netlink_spec/conntrack.rst | 3 +++ .../networking/netlink_spec/devlink.rst | 3 +++ .../networking/netlink_spec/dpll.rst | 3 +++ .../networking/netlink_spec/ethtool.rst | 3 +++ Documentation/networking/netlink_spec/fou.rst | 3 +++ .../networking/netlink_spec/handshake.rst | 3 +++ .../networking/netlink_spec/index.rst | 6 ++++++ .../networking/netlink_spec/lockd.rst | 3 +++ .../networking/netlink_spec/mptcp_pm.rst | 3 +++ .../networking/netlink_spec/net_shaper.rst | 3 +++ .../networking/netlink_spec/netdev.rst | 3 +++ .../networking/netlink_spec/nfsd.rst | 3 +++ .../networking/netlink_spec/nftables.rst | 3 +++ .../networking/netlink_spec/nl80211.rst | 3 +++ .../networking/netlink_spec/nlctrl.rst | 3 +++ .../networking/netlink_spec/ovpn.rst | 3 +++ .../networking/netlink_spec/ovs_datapath.rst | 3 +++ .../networking/netlink_spec/ovs_flow.rst | 3 +++ .../networking/netlink_spec/ovs_vport.rst | 3 +++ .../networking/netlink_spec/readme.txt | 4 ---- .../networking/netlink_spec/rt-addr.rst | 3 +++ .../networking/netlink_spec/rt-link.rst | 3 +++ .../networking/netlink_spec/rt-neigh.rst | 3 +++ .../networking/netlink_spec/rt-route.rst | 3 +++ .../networking/netlink_spec/rt-rule.rst | 3 +++ Documentation/networking/netlink_spec/tc.rst | 3 +++ .../networking/netlink_spec/tcp_metrics.rst | 3 +++ .../networking/netlink_spec/team.rst | 3 +++ tools/net/ynl/pyynl/ynl_gen_rst.py | 19 +++++++++++++------ 30 files changed, 101 insertions(+), 14 deletions(-) create mode 100644 Documentation/networking/netlink_spec/conntrack.rst create mode 100644 Documentation/networking/netlink_spec/devlink.rst create mode 100644 Documentation/networking/netlink_spec/dpll.rst create mode 100644 Documentation/networking/netlink_spec/ethtool.rst create mode 100644 Documentation/networking/netlink_spec/fou.rst create mode 100644 Documentation/networking/netlink_spec/handshake.rst create mode 100644 Documentation/networking/netlink_spec/index.rst create mode 100644 Documentation/networking/netlink_spec/lockd.rst create mode 100644 Documentation/networking/netlink_spec/mptcp_pm.rst create mode 100644 Documentation/networking/netlink_spec/net_shaper.rst create mode 100644 Documentation/networking/netlink_spec/netdev.rst create mode 100644 Documentation/networking/netlink_spec/nfsd.rst create mode 100644 Documentation/networking/netlink_spec/nftables.rst create mode 100644 Documentation/networking/netlink_spec/nl80211.rst create mode 100644 Documentation/networking/netlink_spec/nlctrl.rst create mode 100644 Documentation/networking/netlink_spec/ovpn.rst create mode 100644 Documentation/networking/netlink_spec/ovs_datapath.rst create mode 100644 Documentation/networking/netlink_spec/ovs_flow.rst create mode 100644 Documentation/networking/netlink_spec/ovs_vport.rst delete mode 100644 Documentation/networking/netlink_spec/readme.txt create mode 100644 Documentation/networking/netlink_spec/rt-addr.rst create mode 100644 Documentation/networking/netlink_spec/rt-link.rst create mode 100644 Documentation/networking/netlink_spec/rt-neigh.rst create mode 100644 Documentation/networking/netlink_spec/rt-route.rst create mode 100644 Documentation/networking/netlink_spec/rt-rule.rst create mode 100644 Documentation/networking/netlink_spec/tc.rst create mode 100644 Documentation/networking/netlink_spec/tcp_metrics.rst create mode 100644 Documentation/networking/netlink_spec/team.rst diff --git a/Documentation/Makefile b/Documentation/Makefile index d30d66ddf1ad..2383825dba49 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -102,8 +102,8 @@ 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_INDEX:=3D$(BUILDDIR)/networking/netlink_spec/netlink_index.rst +YNL_RST_DIR:=3D$(BUILDDIR)/networking/netlink_spec/ YNL_YAML_DIR:=3D$(srctree)/Documentation/netlink/specs YNL_TOOL:=3D$(srctree)/tools/net/ynl/pyynl/ynl_gen_rst.py =20 @@ -111,12 +111,12 @@ YNL_RST_FILES_TMP :=3D $(patsubst %.yaml,%.rst,$(wild= card $(YNL_YAML_DIR)/*.yaml)) YNL_RST_FILES :=3D $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_= FILES_TMP)) =20 $(YNL_INDEX): $(YNL_RST_FILES) - $(Q)$(YNL_TOOL) -o $@ -x + $(Q)$(YNL_TOOL) -o $@ -d $(YNL_YAML_DIR) -x =20 $(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL) $(Q)$(YNL_TOOL) -i $< -o $@ =20 -htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX) +htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX) $(YNL_RST_FI= LES) =20 htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check diff --git a/Documentation/networking/netlink_spec/conntrack.rst b/Document= ation/networking/netlink_spec/conntrack.rst new file mode 100644 index 000000000000..6fc6af1e6de4 --- /dev/null +++ b/Documentation/networking/netlink_spec/conntrack.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/conntrack.rst diff --git a/Documentation/networking/netlink_spec/devlink.rst b/Documentat= ion/networking/netlink_spec/devlink.rst new file mode 100644 index 000000000000..412295d396c1 --- /dev/null +++ b/Documentation/networking/netlink_spec/devlink.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/devlink.rst diff --git a/Documentation/networking/netlink_spec/dpll.rst b/Documentation= /networking/netlink_spec/dpll.rst new file mode 100644 index 000000000000..913e1d9ef744 --- /dev/null +++ b/Documentation/networking/netlink_spec/dpll.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/dpll.rst diff --git a/Documentation/networking/netlink_spec/ethtool.rst b/Documentat= ion/networking/netlink_spec/ethtool.rst new file mode 100644 index 000000000000..42136a8572b9 --- /dev/null +++ b/Documentation/networking/netlink_spec/ethtool.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/ethtool.rst diff --git a/Documentation/networking/netlink_spec/fou.rst b/Documentation/= networking/netlink_spec/fou.rst new file mode 100644 index 000000000000..103528337d46 --- /dev/null +++ b/Documentation/networking/netlink_spec/fou.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/fou.rst diff --git a/Documentation/networking/netlink_spec/handshake.rst b/Document= ation/networking/netlink_spec/handshake.rst new file mode 100644 index 000000000000..600abec80431 --- /dev/null +++ b/Documentation/networking/netlink_spec/handshake.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/handshake.rst diff --git a/Documentation/networking/netlink_spec/index.rst b/Documentatio= n/networking/netlink_spec/index.rst new file mode 100644 index 000000000000..8a07a77f2e8b --- /dev/null +++ b/Documentation/networking/netlink_spec/index.rst @@ -0,0 +1,6 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Netlink documentation is populated during the build of the documentation +# (htmldocs) by the tools/net/ynl/pyynl/ynl_gen_rst.py script. + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/netlink_index.rst diff --git a/Documentation/networking/netlink_spec/lockd.rst b/Documentatio= n/networking/netlink_spec/lockd.rst new file mode 100644 index 000000000000..6374dc2a982c --- /dev/null +++ b/Documentation/networking/netlink_spec/lockd.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/lockd.rst diff --git a/Documentation/networking/netlink_spec/mptcp_pm.rst b/Documenta= tion/networking/netlink_spec/mptcp_pm.rst new file mode 100644 index 000000000000..8923db35603e --- /dev/null +++ b/Documentation/networking/netlink_spec/mptcp_pm.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/mptcp_pm.rst diff --git a/Documentation/networking/netlink_spec/net_shaper.rst b/Documen= tation/networking/netlink_spec/net_shaper.rst new file mode 100644 index 000000000000..82d9300f1c0c --- /dev/null +++ b/Documentation/networking/netlink_spec/net_shaper.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/net_shaper.rst diff --git a/Documentation/networking/netlink_spec/netdev.rst b/Documentati= on/networking/netlink_spec/netdev.rst new file mode 100644 index 000000000000..c379a79c5f23 --- /dev/null +++ b/Documentation/networking/netlink_spec/netdev.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/netdev.rst diff --git a/Documentation/networking/netlink_spec/nfsd.rst b/Documentation= /networking/netlink_spec/nfsd.rst new file mode 100644 index 000000000000..40716f4a3fa8 --- /dev/null +++ b/Documentation/networking/netlink_spec/nfsd.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/nfsd.rst diff --git a/Documentation/networking/netlink_spec/nftables.rst b/Documenta= tion/networking/netlink_spec/nftables.rst new file mode 100644 index 000000000000..1dc6d7c5ca58 --- /dev/null +++ b/Documentation/networking/netlink_spec/nftables.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/nftables.rst diff --git a/Documentation/networking/netlink_spec/nl80211.rst b/Documentat= ion/networking/netlink_spec/nl80211.rst new file mode 100644 index 000000000000..c056418f7068 --- /dev/null +++ b/Documentation/networking/netlink_spec/nl80211.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/nl80211.rst diff --git a/Documentation/networking/netlink_spec/nlctrl.rst b/Documentati= on/networking/netlink_spec/nlctrl.rst new file mode 100644 index 000000000000..7fe48f26718e --- /dev/null +++ b/Documentation/networking/netlink_spec/nlctrl.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/nlctrl.rst diff --git a/Documentation/networking/netlink_spec/ovpn.rst b/Documentation= /networking/netlink_spec/ovpn.rst new file mode 100644 index 000000000000..c146b803d742 --- /dev/null +++ b/Documentation/networking/netlink_spec/ovpn.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/ovpn.rst diff --git a/Documentation/networking/netlink_spec/ovs_datapath.rst b/Docum= entation/networking/netlink_spec/ovs_datapath.rst new file mode 100644 index 000000000000..0b1242f2cc9c --- /dev/null +++ b/Documentation/networking/netlink_spec/ovs_datapath.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/ovs_datapath.rst diff --git a/Documentation/networking/netlink_spec/ovs_flow.rst b/Documenta= tion/networking/netlink_spec/ovs_flow.rst new file mode 100644 index 000000000000..c1019ab06aff --- /dev/null +++ b/Documentation/networking/netlink_spec/ovs_flow.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/ovs_flow.rst diff --git a/Documentation/networking/netlink_spec/ovs_vport.rst b/Document= ation/networking/netlink_spec/ovs_vport.rst new file mode 100644 index 000000000000..13eb53ff4c75 --- /dev/null +++ b/Documentation/networking/netlink_spec/ovs_vport.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/ovs_vport.rst 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/networking/netlink_spec/rt-addr.rst b/Documentat= ion/networking/netlink_spec/rt-addr.rst new file mode 100644 index 000000000000..2739e81b7a04 --- /dev/null +++ b/Documentation/networking/netlink_spec/rt-addr.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/rt-addr.rst diff --git a/Documentation/networking/netlink_spec/rt-link.rst b/Documentat= ion/networking/netlink_spec/rt-link.rst new file mode 100644 index 000000000000..d4df7268d07c --- /dev/null +++ b/Documentation/networking/netlink_spec/rt-link.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/rt-link.rst diff --git a/Documentation/networking/netlink_spec/rt-neigh.rst b/Documenta= tion/networking/netlink_spec/rt-neigh.rst new file mode 100644 index 000000000000..6c8b62d7b2ff --- /dev/null +++ b/Documentation/networking/netlink_spec/rt-neigh.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/rt-neigh.rst diff --git a/Documentation/networking/netlink_spec/rt-route.rst b/Documenta= tion/networking/netlink_spec/rt-route.rst new file mode 100644 index 000000000000..a629d14bf405 --- /dev/null +++ b/Documentation/networking/netlink_spec/rt-route.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/rt-route.rst diff --git a/Documentation/networking/netlink_spec/rt-rule.rst b/Documentat= ion/networking/netlink_spec/rt-rule.rst new file mode 100644 index 000000000000..e4a991b1bacd --- /dev/null +++ b/Documentation/networking/netlink_spec/rt-rule.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/rt-rule.rst diff --git a/Documentation/networking/netlink_spec/tc.rst b/Documentation/n= etworking/netlink_spec/tc.rst new file mode 100644 index 000000000000..1e78d3caeb5d --- /dev/null +++ b/Documentation/networking/netlink_spec/tc.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/tc.rst diff --git a/Documentation/networking/netlink_spec/tcp_metrics.rst b/Docume= ntation/networking/netlink_spec/tcp_metrics.rst new file mode 100644 index 000000000000..ea43bd6f6925 --- /dev/null +++ b/Documentation/networking/netlink_spec/tcp_metrics.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/tcp_metrics.rst diff --git a/Documentation/networking/netlink_spec/team.rst b/Documentation= /networking/netlink_spec/team.rst new file mode 100644 index 000000000000..45a3f4d3ed80 --- /dev/null +++ b/Documentation/networking/netlink_spec/team.rst @@ -0,0 +1,3 @@ +# SPDX-License-Identifier: GPL-2.0 + +.. kernel-include:: $BUILDDIR/networking/netlink_spec/team.rst diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_g= en_rst.py index 7bfb8ceeeefc..70417a9a8e96 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,15 @@ 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) + if not index_dir: + index_dir =3D os.path.dirname(output) + + logging.debug("Looking for .yaml 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(".yaml") or filename =3D=3D index_fname: continue - lines.append(f" {filename.replace('.rst', '')}\n") + lines.append(f" {filename.replace('.yaml', '')}\n") =20 logging.debug("Writing an index file at %s", output) write_to_rstfile("".join(lines), output) @@ -447,7 +454,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