Hi Breno, Em Tue, 10 Jun 2025 08:43:55 -0700 Breno Leitao <leitao@xxxxxxxxxx> 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@xxxxxxxxxx/ 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
