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: <8a885d30b9915e80a86e4096a0b4a1fb13616a95@intel.com>
Date: Fri, 16 Jan 2026 12:38:25 +0200
From: Jani Nikula <jani.nikula@...ux.intel.com>
To: Jonathan Corbet <corbet@....net>, Randy Dunlap <rdunlap@...radead.org>,
 Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: 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

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.

The wrapper script is the stable interface that can hide the actual
location and structure of the python packages and sources, and set up
the python environment.

While I'm not suggesting to package kernel-doc for pypi, I think
structuring it in a way that it could be is a fairly good guideline for
managing the source. And I feel like all the other refactoring and
relocation is already taking us in this direction.

BR,
Jani.

-- 
Jani Nikula, Intel