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

[Breno Leitao <leitao@debian.org>]

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