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: <21372af21ce06af04d6c6fbfff3432118dc2483f@intel.com>
Date: Thu, 15 Jan 2026 14:58:40 +0200
From: Jani Nikula <jani.nikula@...ux.intel.com>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Jonathan Corbet <corbet@....net>, 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

On Thu, 15 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> Em Thu, 15 Jan 2026 12:33:10 +0200
> Jani Nikula <jani.nikula@...ux.intel.com> escreveu:
>
>> On Wed, 14 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
>> > Em Wed, 14 Jan 2026 12:24:31 -0700
>> > Jonathan Corbet <corbet@....net> escreveu:
>> >  
>> >> Randy Dunlap <rdunlap@...radead.org> writes:
>> >>   
>> >> > I do many of these on a regular basis:
>> >> >
>> >> > $ ./scripts/kernel-doc -none -Wall <path_to_source_file>
>> >> >
>> >> > Will I still be able to do that (by using ./tools/doc/kernel-doc ...)?    
>> >> 
>> >> Yes.  The tool moves, but its functionality remains unchanged.  
>> >
>> > That's actually a good point: should we preserve a link on scripts
>> > pointing to ../tools/doc/kernel-doc? I suspect that a change like
>> > that could break some machinery on several CI tools and scripts
>> > out there. If so, it could be useful to keep a link - at least for
>> > a couple of kernel releases.  
>> 
>> I think the tool source should be called kernel_doc.py or something, and
>> scripts/kernel-doc should be a script running the former.
>
> Works for me.
>
>> In regular python projects the script would be generated based on
>> pyproject.toml or something, but regardless the source file name would
>> adhere to PEP requirements.
>
> Agreed.
>
>> Additionally, the kernel-doc source could be a package under
>> tools/lib/python, with __main__.py so you could run it using the package
>> name 'python3 -m foo' style.
>
> This is where we diverge: all the code needed to produce docs are
> already inside modules which are called directly via Sphinx extension. 
>
> So, I can't see an advantage on moving main to __main__.py.

The main() doesn't have to be in __main__.py, and I didn't suggest
so. But if there's a package that contains the kernel-doc cli, it would
be quite normal to have a __main__.py to run the cli, so that 'python3
-m package' works, and you don't have to know or specify the exact file
the main() function resides in.

BR,
Jani.


>
>
> Thanks,
> Mauro

-- 
Jani Nikula, Intel