Em Sat, 14 Jun 2025 12:46:49 -0700
Jakub Kicinski [off-list ref] escreveu:

On Sat, 14 Jun 2025 20:56:09 +0200 Mauro Carvalho Chehab wrote:

quoted

quoted

I understand that from the PoV of ease of maintenance of the docs.
Is it fair to say there is a trade off here between ease of maintenance
for docs maintainers and encouraging people to integrate with kernel
docs in novel ways?    

Placing elsewhere won't make much difference from doc maintainers and
developers.  

I must be missing your point. Clearly it makes a difference to Donald,
who is a maintainer of the docs in question.

Heh, I was just saying that I missed your point ;-)

See, you said that "there is a trade off here between ease of maintenance
for docs maintainers and encouraging people to integrate with kernel
docs in novel ways".

I can't see how being easy/hard to maintain or even "integrate with
kernel docs in novel ways" would be affected by the script location.

Whatever it is located, there should be MAINTAINERS entries that would
point to YAML and network maintainers maintainers:

	$ ./scripts/get_maintainer.pl tools/net/ynl/pyynl/ynl_gen_rst.py --nogit --nogit-blame --nogit-fallback
	Donald Hunter [off-list ref] (maintainer:YAML NETLINK (YNL))
	Jakub Kicinski [off-list ref] (maintainer:YAML NETLINK (YNL))
	"David S. Miller" [off-list ref] (maintainer:NETWORKING [GENERAL])
	Eric Dumazet [off-list ref] (maintainer:NETWORKING [GENERAL])
	Paolo Abeni [off-list ref] (maintainer:NETWORKING [GENERAL])
	Simon Horman [off-list ref] (reviewer:NETWORKING [GENERAL])
	netdev@vger.kernel.org (open list:NETWORKING [GENERAL])
	linux-kernel@vger.kernel.org (open list)
	YAML NETLINK (YNL) status: Unknown

	(do they all apply to YNL doc parser?)

Plus having doc ML/Maintainer on it:

	Jonathan Corbet [off-list ref] (maintainer:DOCUMENTATION)
	linux-doc@vger.kernel.org (open list:DOCUMENTATION)

So, at least the file called by the Sphinx class should be at the
linux-doc entry at the maintainers' file.

The rationale is that linux-doc and Jon should be c/c, just in case some 
change there might end causing build issues using a version of the toolchain
that is officially supported, as documented at
Documentation/process/changes.rst, e.g. currently whatever it there is 
expected to be compatible with:

	====================== ===============  ========================================
	        Program        Minimal version       Command to check the version
	====================== ===============  ========================================
	...
	Sphinx\ [#f1]_         3.4.3            sphinx-build --version
	...
	Python (optional)      3.9.x            python3 --version
	...


This is independent if the YNL classes are either at scripts/lib
or at tools/net/ynl/pyynl/lib.

quoted

I'm more interested on having a single place where python libraries
could be placed.  

Me too, especially for selftests. But it's not clear to me that
scripts/ is the right location. I thought purely user space code
should live in tools/ and bulk of YNL is for user space.

Several scripts under scripts/ are meant to run outside build
time. One clear example is:

	$ ./scripts/get_abi.py undefined

That basically checks if the userspace sysfs API is properly
documented, by reading the macine's sysfs node and comparing
with the uAPI documentation. Such tool can also used to check if
the ABI documentation Python classes are working as expected.

So, it is a mix of kernel build time and userspace.

There are also pure userspace tools like those two:

	./scripts/get_dvb_firmware
	./scripts/extract_xc3028.pl	

Both extract firmware files from some other OS and write as a
Linux firmware file to be stored under /lib/firmware. They are
userspace-only tools.

-

From my side, I don't care where Python classes would be placed,
but I prefer having them on a single common place. It could be:

	/scripts/lib
	/tools/lib
	/python/lib

eventually with their own sub-directories on it, like what we have
today:

	${some_prefix}/kdoc
	${some_prefix}/abi

In the case of netlink, it could be:

	${some_prefix}/netlink

Yet, IMO, we should not have a different location for userspace
and non-userspace, as it is very hard to draw the borders on several
cases, like the ABI toolset.

quoted

Eventually, some classes might be re-used in the future
by multiple scripts and subsystems, when it makes sense, just like we do
already with Kernel's kAPIs. This also helps when checking what is the
Python's minimal version that are required by the Kernel when updating
it at:  

I think this is exactly the same point Donald is making, but from YNL
perspective. The hope is to share more code between the ReST generator,
the existing C generator and Python library. The later two are already
based on a shared spec model.

That makes perfect sense to me. Yet, this doesn't preventing having
a:

	${some_prefix}/ynl

directory where you would place Netlink YNL parsing, where the prefix
would be either:

	- /scripts/lib
	- /tools/lib
	- /python/lib
	- something else

It may even use some common classes under:

	${some_prefix}/${some_common_prefix}

---

Now, seeing your comments, maybe the main point is wheather it is OK to 
add userspace libraries to scripts/lib or not. IMO, using "/scripts/lib"
is OK, no matter if the script is kernel-build related or "pure userspace",
but if there are no consensus, we could migrate what we have to
"python/lib" or to some other place.


Thanks,
Mauro