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 for Android: free password hash cracker in your pocket

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

Message-ID: <aEmm4bHxn3+l0vDO@gmail.com>
Date: Wed, 11 Jun 2025 08:55:13 -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 Wed, Jun 11, 2025 at 05:45:18PM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 10 Jun 2025 08:43:55 -0700
> Breno Leitao <leitao@...ian.org> escreveu:
> 
> > 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
> 
> Hi Breno,
> 
> I did here a test creating a completely new repository using
> sphinx-quickstart, adding yaml to conf.py with:
> 
> 	source_suffix = ['.rst', '.yaml']
> 
> There, I imported your v1 patch from:
> 	https://lore.kernel.org/all/20231103135622.250314-1-leitao@debian.org/
> 
> While your extension seems to require some work, as it has issues
> processing the current patch, it *is* creating one html file per each
> yaml, without needing any template. All it is needed there is to place
> an yaml file somewhere under source/ directory:

Thanks for the tests. It appears that the sphinx extension can function
without requiring stubs and templates, right?

Given you have your hands dirty with it, and probably more experience
than I have with sphinx extensions, would you be willing to take
ownership of this extension and submit it? I'd be more than happy
to review it.

--breno