Re: [PATCH 07/13] docs: move sphinx-pre-install to tools/doc

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

Em Fri, 15 Aug 2025 13:31:45 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> >> I'm not sure we need the common/docs intermediate directory.
> >> 
> >> Meanwhile, I had a related, possibly unpopular idea...  Start with
> >> .../tools/python/kernel and put a basic __init__.py file there;
> >> everything else would go into that directory or before.  The imports
> >> would then read something like:
> >> 
> >>   from kernel import abi_parser  
> >
> > Not against something similar to it, but IMO "kernel" is a bad
> > name as it sounds something that runs in kernel stace or for Kernel
> > build. It could be, instead:
> >
> > 	from lib import abi_parser  
> 
> Part of my purpose was to make it clear that the import was coming from
> our own library - to distinguish it from all of the other imports that
> these programs have.  "Kernel" seems good to me, but we could call it
> "kernel_lib" or some such if we really want.  "lib" seems too generic.

Ok. let's stick with "Kernel" then.

> > Yet, I guess it may still need to add something at PATH, depending from
> > where current working dir the script was called (but tests required).  
> 
> That seems hard to avoid, yes.
> 
> Of course, we could require that all kernel tools run in a special
> virtualenv :)

No need. Yet, if you look at sphinx-build-wrapper, it has a "-V"
command line. If used, it will either pick a venv name or seek for
sphinx_latest and run from there. I wrote it mainly to help me
on my main devel machine, where I opted to have several different
venvs instead of installing via OS.

I was tempted of making the tool autodetect venv, if sphinx-build
is not found. I opted to not do it for now, but keeping it in mind
for a possible future change. There is also a code that detect if
Python is too old, running a newer version of it if found at the
system if required by the tool to run. 

Maybe we can place both logic into a library and let most tools
use it, adjusting the main function call to something like:

	MIN_PYTHON_VERSION = (3, x, y)

	def main(...):
	   ...

	if __name__ == "__main__":
	     run_on_version(MIN_PYTHON_VERSION, run, use_venv_if_available=True)

> > Btw, nothing prevents moving extensions from Documentation/sphinx
> > into tools/sphinx_extensions. We just need to add the path insert
> > at conf.py.  
> 
> I feel less of a need to do that; it seems that the Sphinx-specific
> stuff can stay where it is.  Though I guess I wouldn't scream too loud
> if people really wanted to do that move.

Ok. As on extensions we always have srctree set (sphinx-build-wrapper
warrants that), the PATH will always be relative to the kernel
directory, e.g.:

	srctree = os.path.abspath(os.environ["srctree"])
	sys.path.insert(0, os.path.join(srctree, "tools/python"))

	from Kernel import abi_parser

The only advantage of moving them to tools/python would be to remove
the need of "srctree" env, using instead os.path.dirname(__file__), 
e.g.:

	sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
	from Kernel import abi_parser
	
but still at lease some extensions still need srctree anyway. So,
not really necessary.

So, let's not touch it then.

Thanks,
Mauro