linux-kernel - Re: [PATCH 4/4] docs: netlink: store generated .rst files at Documentation/output

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

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20250612163905.119c2b5e@sal.lan>
Date: Thu, 12 Jun 2025 16:39:05 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jakub Kicinski <kuba@...nel.org>
Cc: Breno Leitao <leitao@...ian.org>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, Jonathan Corbet <corbet@....net>, 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, linux-kernel@...r.kernel.org,
 lkmm@...ts.linux.dev, netdev@...r.kernel.org, peterz@...radead.org,
 stern@...land.harvard.edu
Subject: Re: [PATCH 4/4] docs: netlink: store generated .rst files at
 Documentation/output

Em Tue, 10 Jun 2025 14:07:24 -0700
Jakub Kicinski <kuba@...nel.org> escreveu:

> On Tue, 10 Jun 2025 22:59:11 +0200 Mauro Carvalho Chehab wrote:
> > > The question is, are we OK with the templates that need to be created
> > > for netlink specs?!     
> > 
> > If there's no other way, one might have a tool for maintainers to use
> > to update templates, but yeah, having one template per each yaml
> > is not ideal. I think we need to investigate it better and seek for
> > some alternatives to avoid it.  
> 
> FWIW we have tools/net/ynl/ynl-regen.sh, it regenerates the C code 
> we have committed in the tree (uAPI headers mostly).
> We could add it there. Which is not to distract from your main
> point that not having the templates would be ideal.

With the new Sphinx extension for netlink specs I posted:

	https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t
	https://lore.kernel.org/linux-doc/20250612142438.MED5SEN3C-3RDQI5I1ELC-u8QJEjH8W4vUQRBdyK1tI@z/T/#t

There's no need for a template for each file, although it does require
updating Documentation/netlink/specs/index.rst. There are a couple
of reasons:

	1. on my tests, I got some errors auto-generating it while
	   using:
		 make SPHINXDIRS="networking netlink" htmldocs

	2. a dynamically-generated file will cause a extra
	   warnings at the userspace files that contain the name of the
           netlink spec index.html. Basically, kernel build runs a script
	   which validates that all files under Documentation/ actually
	   exist

	3. adding/renaming files typically require changing
	   MAINTAINERS and/or Makefiles. Updating index.rst
	   accordingly is already expected for documentation.

In any case, as I didn't drop the existing script, you could add a
call inside tools/net/ynl/ynl-regen.sh to:

	tools/net/ynl/pyynl/ynl_gen_rst.py -x  -v -o Documentation/netlink/specs/index.rst

To ensure that nobody would forget updating it.

Regards,
Mauro