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

[Jani Nikula <jani.nikula@linux.intel.com>]

On Thu, 15 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> Em Thu, 15 Jan 2026 12:33:10 +0200
> Jani Nikula <jani.nikula@linux.intel.com> escreveu:
>
>> On Wed, 14 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>> > Em Wed, 14 Jan 2026 12:24:31 -0700
>> > Jonathan Corbet <corbet@lwn.net> escreveu:
>> >  
>> >> Randy Dunlap <rdunlap@infradead.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