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

Em Tue, 10 Jun 2025 14:07:24 -0700
Jakub Kicinski <[email protected]> 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/[email protected]/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