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: <20250611181056.6543e71e@sal.lan>
Date: Wed, 11 Jun 2025 18:10:56 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Donald Hunter <donald.hunter@...il.com>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>, "Jonathan Corbet"
 <corbet@....net>, "Akira Yokosawa" <akiyks@...il.com>, "Breno Leitao"
 <leitao@...ian.org>, "David S. Miller" <davem@...emloft.net>, "Ignacio
 Encinas Rubio" <ignacio@...cinas.com>, "Marco Elver" <elver@...gle.com>,
 "Shuah Khan" <skhan@...uxfoundation.org>, 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

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

> Mauro Carvalho Chehab <mchehab+huawei@...nel.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