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

Hi Breno,

Em Tue, 10 Jun 2025 08:43:55 -0700
Breno Leitao <leitao@...ian.org> escreveu:

> Hello Mauro,
> 
> On Tue, Jun 10, 2025 at 12:46:07PM +0200, Mauro Carvalho Chehab wrote:
> > 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.  
> 
> In fact, This is very similar to what I did initially in v1. And I was
> creating a sphinx extension to handle the generation, have a look here:
> 
> https://lore.kernel.org/all/20231103135622.250314-1-leitao@debian.org/

Heh, I liked that ;-) 

Still, I would try to make the template there just a single line, e.g.
instead of:

	--- /dev/null
	+++ b/Documentation/networking/netlink_spec/devlink.rst
	@@ -0,0 +1,9 @@
	+.. SPDX-License-Identifier: GPL-2.0
	+
	+========================================
	+Family ``devlink`` netlink specification
	+========================================
	+
	+.. contents::
	+
	+.. netlink-spec:: devlink.yaml

I would just add:

	.. netlink-spec:: devlink.yaml

-

With regards to the code itself, IMHO the best would be to place
the yaml conversion code inside a python library (just like we did
with scripts/lib/kdoc) and keep having a command line program to
call it, as it is easier to test/debug parser issues via command line.

> During the review, we agree to move out of the sphinx extension.
> the reasons are the stubs/templates that needs to be created and you are
> creating here.
> 
> So, if we decide to come back to sphinx extension, we can leverage that
> code from v1 ?!

For me, that's fine. Still, I wonder if are there a way to avoid
creating a template for every yaml, while still using a Sphinx extension.

As there is an 1:1 mapping between .yaml files and output files, perhaps
there's a way to teach Sphinx to do the right thing, creating one html
per file. If so, ideally, the best would be to have an index.rst file similar
to this:

	.. SPDX-License-Identifier: GPL-2.0

	======================
	Netlink Specifications
	======================

	.. netlink-specs:: netlink/specs

which would teach the Sphinx extension to look for *.yaml files 
inside Documentation/netlink/specs, parsing them, creating one html
per file and create a TOC here. As there are some Sphinx extensions
that handle non-ReST formats, maybe this or something similar to
it could be possible.

> 
> > -def generate_main_index_rst(output: str) -> None:
> > +def generate_main_index_rst(output: str, index_dir: str, ) -> None:  
> 
> You probably don't need the last , before ).

Sure. 

> 
> Other than that, LGTM.
> 
> 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.

Thanks,
Mauro