| 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: <cover.1749551140.git.mchehab+huawei@kernel.org>
Date: Tue, 10 Jun 2025 12:46:03 +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>,
Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
linux-kernel@...r.kernel.org,
"Paul E. McKenney" <mchehab+huawei@...nel.org>,
joel@...lfernandes.org,
linux-kernel-mentees@...ts.linux.dev,
peterz@...radead.org,
stern@...land.harvard.edu,
Shuah Khan <skhan@...uxfoundation.org>,
Ignacio Encinas Rubio <ignacio@...cinas.com>,
lkmm@...ts.linux.dev,
Marco Elver <elver@...gle.com>,
Breno Leitao <leitao@...ian.org>,
Akira Yokosawa <akiyks@...il.com>,
"David S. Miller" <davem@...emloft.net>,
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>,
netdev@...r.kernel.org
Subject: [PATCH 0/4] Don't generate netlink .rst files inside $(srctree)
As discussed at:
https://lore.kernel.org/all/20250610101331.62ba466f@foz.lan/
changeset f061c9f7d058 ("Documentation: Document each netlink family")
added a logic which generates *.rst files inside $(srctree). This is bad when
O=<BUILDDIR> is used.
A recent change renamed the yaml files used by Netlink, revealing a bad
side effect: as "make cleandocs" don't clean the produced files, symbols
appear duplicated for people that don't build the kernel from scratch.
There are some possible solutions for that. The simplest one, which is what
this series address, places the build files inside Documentation/output.
The changes to do that are simple enough, but has one drawback,
as it requires a (simple) template file for every netlink family file from
netlink/specs. The template is simple enough:
.. kernel-include:: $BUILDDIR/networking/netlink_spec/<family>.rst
Part of the issue is that sphinx-build only produces html files for sources
inside the source tree (Documentation/). Well, such requirement
is already fulfilled, as we do have one *.yaml file per family inside
Documentation/netlink, but those aren't currently processed by Sphinx,
as Documentation/conf.py currently has only:
source_suffix = ['.rst']
To address that, a long term solution is to add '.yaml' to source_suffix
and add an extension at Documentation/sphinx that parses *.yaml files.
Something similar to:
https://github.com/Jakski/sphinxcontrib-autoyaml
This could internally call ynl_gen_rst.py, but some care is needed, as
the yaml extension is also used by devicetree.
Mauro Carvalho Chehab (4):
tools: ynl_gen_rst.py: create a top-level reference
docs: netlink: netlink-raw.rst: use :ref: instead of :doc:
docs: netlink: don't ignore generated rst files
docs: netlink: store generated .rst files at Documentation/output
Documentation/Makefile | 8 +++----
.../networking/netlink_spec/.gitignore | 1 -
.../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 +++
.../userspace-api/netlink/netlink-raw.rst | 6 ++---
tools/net/ynl/pyynl/ynl_gen_rst.py | 24 ++++++++++++-------
32 files changed, 107 insertions(+), 20 deletions(-)
delete mode 100644 Documentation/networking/netlink_spec/.gitignore
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
--
2.49.0
Powered by blists - more mailing lists