Re: [PATCH 4/4] docs: netlink: store generated .rst files at Documentation/output
From: Mauro Carvalho Chehab
Date: Thu Jun 12 2025 - 10:40:35 EST
Em Tue, 10 Jun 2025 14:07:24 -0700
Jakub Kicinski <kuba@xxxxxxxxxx> 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/cover.1749723671.git.mchehab+huawei@xxxxxxxxxx/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