Em Wed, 11 Jun 2025 12:36:57 +0100
Donald Hunter [off-list ref] escreveu:

Mauro Carvalho Chehab [off-list ref] writes:

quoted

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.

quoted

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