Re: [PATCH v4 12/14] MAINTAINERS: add maintainers for netlink_yml_parser.py

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Donald, Jon,

Em Sat, 14 Jun 2025 15:22:16 +0100
Donald Hunter <donald.hunter@gmail.com> escreveu:

> On Sat, 14 Jun 2025 at 09:56, Mauro Carvalho Chehab
> <mchehab+huawei@kernel.org> wrote:
> >
> > The parsing code from tools/net/ynl/pyynl/ynl_gen_rst.py was moved
> > to scripts/lib/netlink_yml_parser.py. Its maintainership
> > is done by Netlink maintainers. Yet, as it is used by Sphinx
> > build system, add it also to linux-doc maintainers, as changes
> > there might affect documentation builds. So, linux-docs ML
> > should ideally be C/C on changes to it.  
> 
> This patch can be dropped from the series when you move the library
> code to tools/net/ynl/pyynl/lib.
> 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  MAINTAINERS | 2 ++
> >  1 file changed, 2 insertions(+)
> >
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index a92290fffa16..2c0b13e5d8fc 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -7202,6 +7202,7 @@ F:        scripts/get_abi.py
> >  F:     scripts/kernel-doc*
> >  F:     scripts/lib/abi/*
> >  F:     scripts/lib/kdoc/*
> > +F:     scripts/lib/netlink_yml_parser.py
> >  F:     scripts/sphinx-pre-install
> >  X:     Documentation/ABI/
> >  X:     Documentation/admin-guide/media/

Adding an entry that would c/c to linux-doc for the parser is
important, as problems there will affect documentation build,
no matter where it is located. Perhaps one option would be to 
create a separate MAINTAINERS entry for it, like:

	YAML NETLINK (YNL) DOC GENERATOR
	M:      Donald Hunter <donald.hunter@gmail.com>
	M:      Jakub Kicinski <kuba@kernel.org>
	F:      <python_lib_location>/netlink_yml_parser.py
	L:      linux-doc@vger.kernel.org

to ensure that changes to it would be C/C to linux-doc.

> > @@ -27314,6 +27315,7 @@ M:      Jakub Kicinski <kuba@kernel.org>
> >  F:     Documentation/netlink/
> >  F:     Documentation/userspace-api/netlink/intro-specs.rst
> >  F:     Documentation/userspace-api/netlink/specs.rst
> > +F:     scripts/lib/netlink_yml_parser.py
> >  F:     tools/net/ynl/

With regards to the location itself, as I said earlier, it is up to
Jon and you to decide.

My preference is to have all Python libraries at the entire Kernel
inside scripts/lib (or at some other common location), no matter where
the caller Python command or in-kernel Sphinx extensions are located.

There is also slight advantage on placing them at the same location:
if we end adding parsers for other subsystems at parse_html.py, having
all of them at the same directory means we don't need to do something
like:

	lib_paths = [
		"tools/net/ynl/pyynl/lib",
		"foo",
		"bar",
		...
	]

	for d in lib_paths:
		sys.path.insert(0, os.path.join(srctree, "scripts/lib"))

	from netlink_yml_parser import YnlDocGenerator        # pylint: disable=C0413
	from foo_yml_parser import FooYamlDocGenerator        # pylint: disable=C0413
	from bar_yml_parser import BarYamlDocGenerator        # pylint: disable=C0413
	...


Thanks,
Mauro