Hi Breno,

Em Tue, 10 Jun 2025 08:43:55 -0700
Breno Leitao [off-list ref] escreveu:

Hello Mauro,

On Tue, Jun 10, 2025 at 12:46:07PM +0200, Mauro Carvalho Chehab wrote:

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.  

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/ (local)

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.

quoted

-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