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] [thread-next>] [day] [month] [year] [list]

Message-ID: <aEhSu56ePZ/QPHUW@gmail.com>
Date: Tue, 10 Jun 2025 08:43:55 -0700
From: Breno Leitao <leitao@...ian.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: 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

Hello Mauro,

On Tue, Jun 10, 2025 at 12:46:07PM +0200, Mauro Carvalho Chehab wrote:
> 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.

In fact, This is very similar to what I did initially in v1. And I was
creating a sphinx extension to handle the generation, have a look here:

https://lore.kernel.org/all/20231103135622.250314-1-leitao@debian.org/

During the review, we agree to move out of the sphinx extension.
the reasons are the stubs/templates that needs to be created and you are
creating here.

So, if we decide to come back to sphinx extension, we can leverage that
code from v1 ?!

> -def generate_main_index_rst(output: str) -> None:
> +def generate_main_index_rst(output: str, index_dir: str, ) -> None:

You probably don't need the last , before ).

Other than that, LGTM.

The question is, are we OK with the templates that need to be created
for netlink specs?! 

Thanks for looking at it,
--breno