| 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.1750925410.git.mchehab+huawei@kernel.org>
Date: Thu, 26 Jun 2025 10:12:56 +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,
Akira Yokosawa <akiyks@...il.com>,
"David S. Miller" <davem@...emloft.net>,
Ignacio Encinas Rubio <ignacio@...cinas.com>,
Marco Elver <elver@...gle.com>,
Shuah Khan <skhan@...uxfoundation.org>,
Donald Hunter <donald.hunter@...il.com>,
Eric Dumazet <edumazet@...gle.com>,
Jan Stancek <jstancek@...hat.com>,
Paolo Abeni <pabeni@...hat.com>,
Ruben Wauters <rubenru09@....com>,
joel@...lfernandes.org,
linux-kernel-mentees@...ts.linux.dev,
lkmm@...ts.linux.dev,
netdev@...r.kernel.org,
peterz@...radead.org,
stern@...land.harvard.edu,
Breno Leitao <leitao@...ian.org>,
Randy Dunlap <rdunlap@...radead.org>,
Jakub Kicinski <mchehab+huawei@...nel.org>,
Simon Horman <mchehab+huawei@...nel.org>
Subject: [PATCH v8 00/13] Don't generate netlink .rst files inside $(srctree)
Hi Jon,
That's the newest version of the parser-yaml series, addressing the points
raised by Donald.
I dropped patches unrelated to the YAML work. Those were already
merged at docs-next.
-
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 and symbols
appear duplicated for people that don't build the kernel from scratch.
This series adds an yaml parser extension and uses an index file with glob for
*. We opted to write such extension in a way that no actual yaml conversion
code is inside it. This makes it flexible enough to handle other types of yaml
files in the future. The actual yaml conversion logic were placed at
netlink_yml_parser.py.
As requested by YNL maintainers, this version has netlink_yml_parser.py
inside tools/net/ynl/pyynl/ directory. I don't like mixing libraries with
binaries, nor to have Python libraries spread all over the Kernel. IMO,
the best is to put all of them on a common place (scripts/lib, python/lib,
lib/python, ...) but, as this can be solved later, for now let's keep it this
way.
---
v8:
- minor fixes based on Donald's feedback;
- removed unrelated patches.
v7:
- Added a patch to cleanup conf.py and address coding style issues;
- Added a docutils version check logic to detect known issues when
building the docs with too old or too new docutils version. The
actuall min/max vesion depends on Sphinx version.
v6:
- YNL doc parser is now at tools/net/ynl/pyynl/lib/doc_generator.py;
- two patches got merged;
- added instructions to test docs with Sphinx 3.4.3 (minimal supported
version);
- minor fixes.
v5:
- some patch reorg;
- netlink_yml_parser.py is now together with ynl tools;
- minor fixes.
v4:
- Renamed the YNL parser class;
- some minor patch cleanups and merges;
- added an extra patch to fix a insert_pattern/exclude_pattern logic when
SPHINXDIRS is used.
v3:
- Two series got merged altogether:
- https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t
- https://lore.kernel.org/linux-doc/cover.1749735022.git.mchehab+huawei@kernel.org
- Added an extra patch to update MAINTAINERS to point to YNL library
- Added a (somewhat unrelated) patch that remove warnings check when
running "make cleandocs".
Mauro Carvalho Chehab (13):
docs: netlink: netlink-raw.rst: use :ref: instead of :doc:
tools: ynl_gen_rst.py: Split library from command line tool
docs: netlink: index.rst: add a netlink index file
tools: ynl_gen_rst.py: cleanup coding style
docs: sphinx: add a parser for yaml files for Netlink specs
docs: use parser_yaml extension to handle Netlink specs
docs: uapi: netlink: update netlink specs link
tools: ynl_gen_rst.py: drop support for generating index files
docs: netlink: remove obsolete .gitignore from unused directory
MAINTAINERS: add netlink_yml_parser.py to linux-doc
tools: netlink_yml_parser.py: add line numbers to parsed data
docs: parser_yaml.py: add support for line numbers from the parser
docs: parser_yaml.py: fix backward compatibility with old docutils
Documentation/Makefile | 17 -
Documentation/conf.py | 20 +-
Documentation/netlink/specs/index.rst | 13 +
Documentation/networking/index.rst | 2 +-
.../networking/netlink_spec/.gitignore | 1 -
.../networking/netlink_spec/readme.txt | 4 -
Documentation/sphinx/parser_yaml.py | 116 +++++
Documentation/userspace-api/netlink/index.rst | 2 +-
.../userspace-api/netlink/netlink-raw.rst | 6 +-
Documentation/userspace-api/netlink/specs.rst | 2 +-
MAINTAINERS | 1 +
tools/net/ynl/pyynl/lib/__init__.py | 2 +
tools/net/ynl/pyynl/lib/doc_generator.py | 398 ++++++++++++++++++
tools/net/ynl/pyynl/ynl_gen_rst.py | 384 +----------------
14 files changed, 558 insertions(+), 410 deletions(-)
create mode 100644 Documentation/netlink/specs/index.rst
delete mode 100644 Documentation/networking/netlink_spec/.gitignore
delete mode 100644 Documentation/networking/netlink_spec/readme.txt
create mode 100755 Documentation/sphinx/parser_yaml.py
create mode 100644 tools/net/ynl/pyynl/lib/doc_generator.py
--
2.49.0
Powered by blists - more mailing lists