Hello Mauro,

On Wed, Jun 11, 2025 at 05:45:18PM +0200, Mauro Carvalho Chehab wrote:

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

quoted

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)

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 ?!

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 ).

Other than that, LGTM.

The question is, are we OK with the templates that need to be created
for netlink specs?! 

Thanks for looking at it,
--breno

Hi Breno,

I did here a test creating a completely new repository using
sphinx-quickstart, adding yaml to conf.py with:

	source_suffix = ['.rst', '.yaml']

There, I imported your v1 patch from:
	https://lore.kernel.org/all/20231103135622.250314-1-leitao@debian.org/ (local)

While your extension seems to require some work, as it has issues
processing the current patch, it *is* creating one html file per each
yaml, without needing any template. All it is needed there is to place
an yaml file somewhere under source/ directory:

Thanks for the tests. It appears that the sphinx extension can function
without requiring stubs and templates, right?

Given you have your hands dirty with it, and probably more experience
than I have with sphinx extensions, would you be willing to take
ownership of this extension and submit it? I'd be more than happy
to review it.

--breno