All of the documentation-related tools have been gathered together in
tools/docs, with one exception: kernel-doc still lives under scripts/.
Move it to its proper home, fixing up a fair number of references along the
way.

This move was delayed because it ran afoul of one other relatively recent
change.  With the conversion of kernel-doc to Python, the Sphinx kerneldoc
extension gained the ability to import the relevant modules directly, but
it also kept the option of running kernel-doc as a separate process.  To
decide which course to take, the extension looks at the kerneldoc_bin
configuration setting; if that setting ends with "kernel-doc.py", it
chooses the import method.

Some of us found that behavior a bit obscure.  It also complicated the task
of moving scripts/kernel-doc.py to tools/docs/kernel-doc.  I tried a couple
of ways of preserving this behavior but ended up with solutions that were
just as obscure.

So I took a different approach.  In the end, the ability to run kernel-doc
as a separate process does not buy us much.  For debugging purposes, it's
easier to just run kernel-doc by hand directly.  So this series simply
removes that capability, simplifying the logic and removing a bunch of
code.  The code that creates the command line remains in case anybody
should ever want a specific invocation to run by hand.

Jonathan Corbet (2):
  docs: kdoc: remove support for an external kernel-doc from sphinx
  Move kernel-doc to tools/docs

 Documentation/conf.py                         |  2 +-
 Documentation/doc-guide/kernel-doc.rst        |  8 +--
 Documentation/kbuild/kbuild.rst               |  2 +-
 Documentation/process/coding-style.rst        |  2 +-
 Documentation/sphinx/kerneldoc.py             | 53 +++----------------
 .../it_IT/doc-guide/kernel-doc.rst            |  8 +--
 .../sp_SP/process/coding-style.rst            |  2 +-
 .../zh_CN/doc-guide/kernel-doc.rst            | 10 ++--
 .../translations/zh_CN/kbuild/kbuild.rst      |  2 +-
 .../zh_CN/process/coding-style.rst            |  2 +-
 .../zh_TW/process/coding-style.rst            |  2 +-
 MAINTAINERS                                   |  2 -
 Makefile                                      |  2 +-
 drivers/gpu/drm/i915/Makefile                 |  2 +-
 scripts/kernel-doc                            |  1 -
 tools/docs/find-unused-docs.sh                |  2 +-
 .../kernel-doc.py => tools/docs/kernel-doc    |  0
 tools/docs/sphinx-build-wrapper               |  2 +-
 18 files changed, 30 insertions(+), 74 deletions(-)
 delete mode 120000 scripts/kernel-doc
 rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)

-- 
2.52.0

On 1/14/26 8:41 AM, Jonathan Corbet wrote:
> All of the documentation-related tools have been gathered together in
> tools/docs, with one exception: kernel-doc still lives under scripts/.
> Move it to its proper home, fixing up a fair number of references along the
> way.
> 
> This move was delayed because it ran afoul of one other relatively recent
> change.  With the conversion of kernel-doc to Python, the Sphinx kerneldoc
> extension gained the ability to import the relevant modules directly, but
> it also kept the option of running kernel-doc as a separate process.  To
> decide which course to take, the extension looks at the kerneldoc_bin
> configuration setting; if that setting ends with "kernel-doc.py", it
> chooses the import method.
> 
> Some of us found that behavior a bit obscure.  It also complicated the task
> of moving scripts/kernel-doc.py to tools/docs/kernel-doc.  I tried a couple
> of ways of preserving this behavior but ended up with solutions that were
> just as obscure.
> 
> So I took a different approach.  In the end, the ability to run kernel-doc
> as a separate process does not buy us much.  For debugging purposes, it's
> easier to just run kernel-doc by hand directly.  So this series simply
> removes that capability, simplifying the logic and removing a bunch of
> code.  The code that creates the command line remains in case anybody
> should ever want a specific invocation to run by hand.
> 
> Jonathan Corbet (2):
>   docs: kdoc: remove support for an external kernel-doc from sphinx
>   Move kernel-doc to tools/docs

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 ...)?


-- 
~Randy

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.

Thanks,

jon

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.

Thanks,
Mauro

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> 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.

So is the location of kernel-doc part of our ABI, or an internal detail?
:)

I'm not deeply opposed to maintaining the symlink, though I'd rather
not.  It won't be for "a couple of releases", though; if the symlink is
there, nothing will ever change.

Thanks,

jon

Em Fri, 16 Jan 2026 10:48:51 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > 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.  
> 
> So is the location of kernel-doc part of our ABI, or an internal detail?
> :)

Surely it is not part of ABI: it can be changed whenever we want.

From my side, I don't mind where it is located: it will take some
time, but my fingers will end learning its new location/name ;-)

> I'm not deeply opposed to maintaining the symlink, though I'd rather
> not.  It won't be for "a couple of releases", though; if the symlink is
> there, nothing will ever change.

I see two reasons why having a symlink:

1. to avoid the risk of eventually breaking someone's CI or scripts.
   This is just a preventive measure, as I'm not aware of anyone
   with such scripts;

2. as you don't want ".py" extension on execs, but PEP8 mandates it, 
   together with replacing "-" with "_", you can have a symlink that
   would make both PEP8 and you happy ;-)

Just my 2 cents.


Thanks,
Mauro

On 1/17/26 2:00 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 16 Jan 2026 10:48:51 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
>> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>>
>>> 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.  
>>
>> So is the location of kernel-doc part of our ABI, or an internal detail?
>> :)
> 
> Surely it is not part of ABI: it can be changed whenever we want.
> 
> From my side, I don't mind where it is located: it will take some
> time, but my fingers will end learning its new location/name ;-)
> 
>> I'm not deeply opposed to maintaining the symlink, though I'd rather
>> not.  It won't be for "a couple of releases", though; if the symlink is
>> there, nothing will ever change.
> 
> I see two reasons why having a symlink:
> 
> 1. to avoid the risk of eventually breaking someone's CI or scripts.
>    This is just a preventive measure, as I'm not aware of anyone
>    with such scripts;

I have some such scripts. And it's easy to update them, but I'd like for them
to be compatible both going forward and backward in kernel versions -- without
having to do something like:

	if [ -x scripts/kernel-doc ]; then
		foo
	elif [ -x tools/docs/kernel-doc ]; then
		baz
	else { help; }

I doubt that I am unique/alone in this.

> 2. as you don't want ".py" extension on execs, but PEP8 mandates it, >    together with replacing "-" with "_", you can have a symlink that
>    would make both PEP8 and you happy ;-)
> 
> Just my 2 cents.


-- 
~Randy

Em Sat, 17 Jan 2026 10:09:56 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 1/17/26 2:00 AM, Mauro Carvalho Chehab wrote:
> > Em Fri, 16 Jan 2026 10:48:51 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >   
> >> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >>  
> >>> 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.    
> >>
> >> So is the location of kernel-doc part of our ABI, or an internal detail?
> >> :)  
> > 
> > Surely it is not part of ABI: it can be changed whenever we want.
> > 
> > From my side, I don't mind where it is located: it will take some
> > time, but my fingers will end learning its new location/name ;-)
> >   
> >> I'm not deeply opposed to maintaining the symlink, though I'd rather
> >> not.  It won't be for "a couple of releases", though; if the symlink is
> >> there, nothing will ever change.  
> > 
> > I see two reasons why having a symlink:
> > 
> > 1. to avoid the risk of eventually breaking someone's CI or scripts.
> >    This is just a preventive measure, as I'm not aware of anyone
> >    with such scripts;  
> 
> I have some such scripts. And it's easy to update them, but I'd like for them
> to be compatible both going forward and backward in kernel versions -- without
> having to do something like:
> 
> 	if [ -x scripts/kernel-doc ]; then
> 		foo
> 	elif [ -x tools/docs/kernel-doc ]; then
> 		baz
> 	else { help; }
> 
> I doubt that I am unique/alone in this.
> 
> > 2. as you don't want ".py" extension on execs, but PEP8 mandates it, 
> >    together with replacing "-" with "_", you can have a symlink that
> >    would make both PEP8 and you happy ;-)

Just to be clear, when I'm talking about PEP8, I'm actually referring
to the language support for import a python code with "import" and "from". 

The rationale is that some day we may end needing using autodoc(*), or
some other Sphinx extension that would require it, like argparse ones:

	https://sphinxcontrib-autoprogram.readthedocs.io/en/stable/
	https://pypi.org/project/sphinxcontrib-autoprogram/

This would avoid the need of documenting some things twice: at the
code and at the documentation itself.

(*) Right now, we don't have any strong reasons to use autodoc on
    kernel-doc exec: the only possible reason on kernel-doc would be
    to avoid documenting return codes twice, but we could do it also
    via argparse, with something like:

	RETURN_CODE=deident("""
	    The return value is:

	    - 0: success or Python version is not compatible with
	      kernel-doc.  If -Werror is not used, it will also
	      return 0 if there are issues at kernel-doc markups;

	    - 1: an abnormal condition happened;

	    - 2: argparse issued an error;

	    - 3: if -Werror is used, and one or more unfiltered parse
		warnings happened.
	""")

	argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
                                description=DESC, epilog=RETURN_CODE)

    Eventually, it could be useful to use an argparse extension in
    the future, if we want to add the help output inside the
    auto-generated docs.

    Anyway, after having this series merged and mine fixing
    the issues with -Werror, I intend to send you a separate patch
    series with something like the above and moving MsgFormatter
    to a separate module.
	
Thanks,
Mauro

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.

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.

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.

BR,
Jani.

-- 
Jani Nikula, Intel

Jani Nikula <jani.nikula@linux.intel.com> writes:

> 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.

I honestly don't get it - why add an extra indirection step here?

Thanks,

jon

On 1/15/26 7:05 AM, Jonathan Corbet wrote:
> Jani Nikula <jani.nikula@linux.intel.com> writes:
> 
>> 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.
> 
> I honestly don't get it - why add an extra indirection step here?

a. compatibility with people in the wild running scripts/kernel-doc

b. adhere to well-known naming conventions.

-- 
~Randy

Randy Dunlap <rdunlap@infradead.org> writes:

> On 1/15/26 7:05 AM, Jonathan Corbet wrote:
>> Jani Nikula <jani.nikula@linux.intel.com> writes:
>> 
>>> 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.
>> 
>> 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.

Thanks,

jon

On Thu, 15 Jan 2026, Jonathan Corbet <corbet@lwn.net> wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
>
>> On 1/15/26 7:05 AM, Jonathan Corbet wrote:
>>> Jani Nikula <jani.nikula@linux.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

Jani Nikula <jani.nikula@linux.intel.com> writes:

> On Thu, 15 Jan 2026, Jonathan Corbet <corbet@lwn.net> wrote:
>> Randy Dunlap <rdunlap@infradead.org> writes:
>>
>>> On 1/15/26 7:05 AM, Jonathan Corbet wrote:
>>>> Jani Nikula <jani.nikula@linux.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.  We could of course fix that up in the
makefile; the sys.path manipulation is only for standalone runs.

> 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.

I suppose.  I sort of see the existing kernel-doc as *being* the wrapper
script. 

> 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.

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.

Thanks,

jon

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

> Jani Nikula <jani.nikula@linux.intel.com> writes:
> 
> > On Thu, 15 Jan 2026, Jonathan Corbet <corbet@lwn.net> wrote:  
> >> Randy Dunlap <rdunlap@infradead.org> writes:
> >>  
> >>> On 1/15/26 7:05 AM, Jonathan Corbet wrote:  
> >>>> Jani Nikula <jani.nikula@linux.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

On 1/15/26 10:04 AM, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
> 
>> On 1/15/26 7:05 AM, Jonathan Corbet wrote:
>>> Jani Nikula <jani.nikula@linux.intel.com> writes:
>>>
>>>> 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.
>>>
>>> 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.

Sure.

>> 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.

Ah, like .py or .pl or .sh.
Yeah, nice to avoid those.

-- 
~Randy

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.


Thanks,
Mauro

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