linux-kernel - Re: [PATCH 0/2] Move kernel-doc to tools/docs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20260117112925.309a7a31@foz.lan>
Date: Sat, 17 Jan 2026 11:29:25 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Jani Nikula <jani.nikula@...ux.intel.com>, Randy Dunlap
 <rdunlap@...radead.org>, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, Akira Yokosawa <akiyks@...il.com>, Shuah Khan
 <shuah@...nel.org>
Subject: Re: [PATCH 0/2] Move kernel-doc to tools/docs

Em Fri, 16 Jan 2026 10:44:04 -0700
Jonathan Corbet <corbet@....net> escreveu:

> Jani Nikula <jani.nikula@...ux.intel.com> writes:
> 
> > On Thu, 15 Jan 2026, Jonathan Corbet <corbet@....net> wrote:  
> >> Randy Dunlap <rdunlap@...radead.org> writes:
> >>  
> >>> On 1/15/26 7:05 AM, Jonathan Corbet wrote:  
> >>>> Jani Nikula <jani.nikula@...ux.intel.com> writes:
> >>>>   
> >>>>> I think the tool source should be called kernel_doc.py or something, and
> >>>>> scripts/kernel-doc should be a script running the former.  
> >>>> 
> >>>> I honestly don't get it - why add an extra indirection step here?  
> >>>
> >>> a. compatibility with people in the wild running scripts/kernel-doc  
> >>
> >> That is easily achieved with a symbolic link if we need it.
> >>  
> >>> b. adhere to well-known naming conventions.  
> >>
> >> The normal convention is to not have language-specific extensions on
> >> commands.  As in "scripts/kernel-doc".  I still don't understand how
> >> making a wrapper script somehow makes this better.  
> >
> > kernel-doc the python source directly messing with sys.path is not
> > great. The python source should be able to assume the environment has
> > been set up, imports work, etc.  
> 
> I agree that's not great.

Avoiding it is not easy:

- Since the beginning, conf.py has a sys.path() to add sphinx dir,
  as otherwise Sphinx won't find the in-kernel extensions.

  This can probably be fixed by prepending "sphinx." to all in-kernel
  extensions, but, if we're willing to do so, I would first rename

	sphinx/ -> kern_sphinx  (or something similar

- For autodoc to work, we either need sys.path() addition or we would
  need to place conf.py at the top level directory. Doable, conf.py
  is not that important to be at the root directory.

> We could of course fix that up in the
> makefile; the sys.path manipulation is only for standalone runs.

I don't think Makefile is the right place to override Python
limitations. The real culprit here is that Python doesn't have
anything similar to:

	#include "../tools/python/lib/foo.py"

If you want to include it, you need to do, instead:

	sys.path.append(os.path.abspath(".."))

	import tools.python.lib.foo

or a variant of that, like:

	sys.path.append(os.path.abspath("../tools/python"))

	import lib.foo

> So I guess my feeling is that if somebody really wants to implement that
> extra level of indirection, we can consider it.  I won't dig in my heels
> *too* deeply.  But it's a separate change from moving the tool, so
> should be done on its own.

I don’t think we need such indirection, nor do we need to avoid using 
sys.path() to overcome Python's parent import limitation. IMO, a
pragmatic rather than a purist approach is more suitable for our needs.

Thanks,
Mauro