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: <20250612122209.0f48fbda@foz.lan>
Date: Thu, 12 Jun 2025 12:22:09 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Breno Leitao <leitao@...ian.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

Hi Breno,

Em Wed, 11 Jun 2025 08:55:13 -0700
Breno Leitao <leitao@...ian.org> escreveu:

> 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.

Sure. I wrote an extension that will do what it is expected. Yet,
I opted to have a static index.rst file. I tried to do auto-generation,
but, at least when using SPHINXDIRS, it didn't work.

I'm sending the patch series in a few.

Thanks,
Mauro