| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <5183ad8aacc1a56e2dce9cc125b62905b93e83ca.1749551140.git.mchehab+huawei@kernel.org>
Date: Tue, 10 Jun 2025 12:46:07 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
"Jonathan Corbet" <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
"Akira Yokosawa" <akiyks@...il.com>,
"Breno Leitao" <leitao@...ian.org>,
"David S. Miller" <davem@...emloft.net>,
"Ignacio Encinas Rubio" <ignacio@...cinas.com>,
"Marco Elver" <elver@...gle.com>,
"Mauro Carvalho Chehab" <mchehab+huawei@...nel.org>,
"Paul E. McKenney" <mchehab+huawei@...nel.org>,
"Shuah Khan" <skhan@...uxfoundation.org>,
Donald Hunter <donald.hunter@...il.com>,
Eric Dumazet <edumazet@...gle.com>,
Jakub Kicinski <mchehab+huawei@...nel.org>,
Jan Stancek <jstancek@...hat.com>,
Paolo Abeni <pabeni@...hat.com>,
Ruben Wauters <rubenru09@....com>,
Simon Horman <mchehab+huawei@...nel.org>,
joel@...lfernandes.org,
linux-kernel-mentees@...ts.linux.dev,
linux-kernel@...r.kernel.org,
lkmm@...ts.linux.dev,
netdev@...r.kernel.org,
peterz@...radead.org,
stern@...land.harvard.edu
Subject: [PATCH 4/4] docs: netlink: store generated .rst files at Documentation/output
It is not a good practice to store build-generated files
inside $(srctree), as one may be using O=<BUILDDIR> 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/<foo>.yaml
.. kernel-include:: $BUILDDIR/networking/netlink_spec/<foo>.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 <mchehab+huawei@...nel.org>
---
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 = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
cp $(if $(patsubst /%,,$(DOCS_CSS)),$(abspath $(srctree)/$(DOCS_CSS)),$(DOCS_CSS)) $(BUILDDIR)/$3/_static/; \
fi
-YNL_INDEX:=$(srctree)/Documentation/networking/netlink_spec/index.rst
-YNL_RST_DIR:=$(srctree)/Documentation/networking/netlink_spec
+YNL_INDEX:=$(BUILDDIR)/networking/netlink_spec/netlink_index.rst
+YNL_RST_DIR:=$(BUILDDIR)/networking/netlink_spec/
YNL_YAML_DIR:=$(srctree)/Documentation/netlink/specs
YNL_TOOL:=$(srctree)/tools/net/ynl/pyynl/ynl_gen_rst.py
@@ -111,12 +111,12 @@ YNL_RST_FILES_TMP := $(patsubst %.yaml,%.rst,$(wildcard $(YNL_YAML_DIR)/*.yaml))
YNL_RST_FILES := $(patsubst $(YNL_YAML_DIR)%,$(YNL_RST_DIR)%, $(YNL_RST_FILES_TMP))
$(YNL_INDEX): $(YNL_RST_FILES)
- $(Q)$(YNL_TOOL) -o $@ -x
+ $(Q)$(YNL_TOOL) -o $@ -d $(YNL_YAML_DIR) -x
$(YNL_RST_DIR)/%.rst: $(YNL_YAML_DIR)/%.yaml $(YNL_TOOL)
$(Q)$(YNL_TOOL) -i $< -o $@
-htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX)
+htmldocs texinfodocs latexdocs epubdocs xmldocs: $(YNL_INDEX) $(YNL_RST_FILES)
htmldocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
diff --git a/Documentation/networking/netlink_spec/conntrack.rst b/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/Documentation/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/networking/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/Documentation/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_gen_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:
parser.add_argument("-v", "--verbose", action="store_true")
parser.add_argument("-o", "--output", help="Output file name")
+ parser.add_argument("-d", "--input_dir", help="YAML input directory")
# Index and input are mutually exclusive
group = 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)
+ dir = os.path.dirname(filename)
+ os.makedirs(dir, exist_ok=True)
+
with open(filename, "w", encoding="utf-8") as rst_file:
rst_file.write(content)
-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 = []
@@ -418,12 +422,15 @@ def generate_main_index_rst(output: str) -> None:
lines.append(rst_title("Netlink Family Specifications"))
lines.append(rst_toctree(1))
- index_dir = os.path.dirname(output)
- logging.debug("Looking for .rst files in %s", index_dir)
+ index_fname = os.path.basename(output)
+ if not index_dir:
+ index_dir = 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 == "index.rst":
+ if not filename.endswith(".yaml") or filename == index_fname:
continue
- lines.append(f" {filename.replace('.rst', '')}\n")
+ lines.append(f" {filename.replace('.yaml', '')}\n")
logging.debug("Writing an index file at %s", output)
write_to_rstfile("".join(lines), output)
@@ -447,7 +454,7 @@ def main() -> None:
if args.index:
# Generate the index RST file
- generate_main_index_rst(args.output)
+ generate_main_index_rst(args.output, args.input_dir)
if __name__ == "__main__":
--
2.49.0
Powered by blists - more mailing lists