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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed, 11 Jun 2025 12:36:57 +0100
Donald Hunter <donald.hunter@gmail.com> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > It is not a good practice to store build-generated files
> > inside $(srctree), as one may be using O=<BUILDDIR> and even
> > have the Kernel on a read-only directory.
> >
> > Change the YAML generation for netlink files to be inside
> > the documentation output directory.
> >
> > This solution is not perfect, though, as sphinx-build only produces
> > html files only for files inside the source tree. As it is desired
> > to have one netlink file per family, it means that one template
> > file is required for every file inside Documentation/netlink/specs.
> > Such template files are simple enough. All they need is:
> >
> > 	# Template for Documentation/netlink/specs/<foo>.yaml
> > 	.. kernel-include:: $BUILDDIR/networking/netlink_spec/<foo>.rst  
> 
> I am not a fan of this approach because it pollutes the
> Documentation/output dir with source files and the kernel-include
> directive is a bit of a hacky workaround.
> 
> > 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.  
> 
> The extension does seem like a better approach, but as mentioned by
> Jakub, we'd want to add stub creation to the YNL regen.
> 
> The only other approach I can think of to avoid generating files in the
> source tree or polluting the Documentation/output dir is to stage all of
> the Documentation/ tree into BUILDDIR before adding generated files
> there, then running:
> 
>   sphinx-build BUILDDIR/Documentation BUILDDIR/Documentation/output

I did some tests here adding yaml to conf.py:

	-source_suffix = '.rst'
	+source_suffix = ['.rst', '.yaml']

Such change made the extension to automatically generate one file per 
each existing yaml without the need of adding any template. I tested on 
a brand new tree with just Sphinx + netlink files + Breno's original
extension (untouched). Such empty tree was generated with 
sphinx-quickstart (sent a reply to Breno with a patch with all inside
it).

When applying it to the Kernel, we can do this change at
Documentation/conf.py, together with:

	-exclude_patterns = ['output']
	+exclude_patterns = ['output', 'devicetree/bindings/**.yaml']

(glob pattern not tested)

As we don't want DT yaml files to be processed as netlink families.

After such tests, it sounds to me that the Sphinx extension approach 
may work without requiring templates. Tested here with Sphinx 8.1.3.

Regards,
Mauro