Our documentation-related tools are spread out over various directories;
several are buried in the scripts/ dumping ground.  That makes them harder
to discover and harder to maintain.

Recent work has started accumulating our documentation-related tools in
/tools/docs.  This series completes that task, moving the rest of our
various utilities there, hopefully fixing up all of the relevant references
in the process.

At the end, rather than move the old, Perl kernel-doc, I simply removed it.

The big elephant lurking in this small room is the home for Python modules;
I left them under scripts/lib, but that is an even less appropriate place
than it was before.  I would propose either tools/python or lib/python;
thoughts on that matter welcome.

Changes in v3:
  - Now with more caffeine! Properly based on docs-next.

Changes in v2:
  - Rebase on top of all of Mauro's changes (the most painful rebase I've
    ever done, I think).
  - Land everything in /tools/docs/ rather than /tools/doc/

v2: https://lore.kernel.org/lkml/20251023161027.697135-1-corbet@lwn.net/
v1: https://lore.kernel.org/lkml/20250813213218.198582-1-corbet@lwn.net/


Jonathan Corbet (8):
  docs: Move the "features" tools to tools/docs
  docs: move checktransupdate.py to tools/docs
  docs: move scripts/documentation-file-ref-check to tools/docs
  docs: move get_abi.py to tools/docs
  docs: move test_doc_build.py to tools/docs
  docs: move kernel-doc to tools/docs
  docs: move find-unused-docs.sh to tools/docs
  docs: remove kernel-doc.pl

 Documentation/Kconfig                         |    2 +-
 Documentation/Makefile                        |    6 +-
 Documentation/conf.py                         |    2 +-
 Documentation/doc-guide/checktransupdate.rst  |    6 +-
 Documentation/doc-guide/contributing.rst      |    2 +-
 Documentation/doc-guide/kernel-doc.rst        |    6 +-
 Documentation/doc-guide/sphinx.rst            |    2 +-
 Documentation/kbuild/kbuild.rst               |    2 +-
 Documentation/process/coding-style.rst        |    2 +-
 Documentation/sphinx/kernel_abi.py            |    2 +-
 Documentation/sphinx/kernel_feat.py           |    4 +-
 .../it_IT/doc-guide/kernel-doc.rst            |    8 +-
 .../sp_SP/process/coding-style.rst            |    2 +-
 .../zh_CN/doc-guide/checktransupdate.rst      |    6 +-
 .../zh_CN/doc-guide/contributing.rst          |    2 +-
 .../zh_CN/doc-guide/kernel-doc.rst            |   10 +-
 Documentation/translations/zh_CN/how-to.rst   |    2 +-
 .../translations/zh_CN/kbuild/kbuild.rst      |    2 +-
 .../zh_CN/process/coding-style.rst            |    2 +-
 .../zh_TW/process/coding-style.rst            |    2 +-
 MAINTAINERS                                   |    5 -
 Makefile                                      |    2 +-
 drivers/gpu/drm/i915/Makefile                 |    2 +-
 scripts/kernel-doc                            |    1 -
 scripts/kernel-doc.pl                         | 2439 -----------------
 {scripts => tools/docs}/checktransupdate.py   |    8 +-
 .../docs}/documentation-file-ref-check        |    2 +-
 .../docs}/features-refresh.sh                 |    0
 {scripts => tools/docs}/find-unused-docs.sh   |    8 +-
 {scripts => tools/docs}/get_abi.py            |    0
 {scripts => tools/docs}/get_feat.pl           |    2 +-
 .../kernel-doc.py => tools/docs/kernel-doc    |    0
 .../features => tools/docs}/list-arch.sh      |    2 +-
 tools/docs/sphinx-pre-install                 |    2 +-
 {scripts => tools/docs}/test_doc_build.py     |    0
 35 files changed, 50 insertions(+), 2495 deletions(-)
 delete mode 120000 scripts/kernel-doc
 delete mode 100755 scripts/kernel-doc.pl
 rename {scripts => tools/docs}/checktransupdate.py (97%)
 rename {scripts => tools/docs}/documentation-file-ref-check (99%)
 rename {Documentation/features/scripts => tools/docs}/features-refresh.sh (100%)
 rename {scripts => tools/docs}/find-unused-docs.sh (79%)
 rename {scripts => tools/docs}/get_abi.py (100%)
 rename {scripts => tools/docs}/get_feat.pl (99%)
 rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)
 rename {Documentation/features => tools/docs}/list-arch.sh (83%)
 rename {scripts => tools/docs}/test_doc_build.py (100%)

-- 
2.51.0

On 10/24/25 1:08 PM, Jonathan Corbet wrote:
> The big elephant lurking in this small room is the home for Python modules;
> I left them under scripts/lib, but that is an even less appropriate place
> than it was before.  I would propose either tools/python or lib/python;
> thoughts on that matter welcome.

I agree with Jani-- not lib/.
if that helps.

-- 
~Randy

On Fri, 24 Oct 2025 14:08:21 -0600, Jonathan Corbet wrote:
> Our documentation-related tools are spread out over various directories;
> several are buried in the scripts/ dumping ground.  That makes them harder
> to discover and harder to maintain.
> 
> Recent work has started accumulating our documentation-related tools in
> /tools/docs.  This series completes that task, moving the rest of our
> various utilities there, hopefully fixing up all of the relevant references
> in the process.
> 
> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
> 
> The big elephant lurking in this small room is the home for Python modules;
> I left them under scripts/lib, but that is an even less appropriate place
> than it was before.  I would propose either tools/python or lib/python;
> thoughts on that matter welcome.
> 
> Changes in v3:
>   - Now with more caffeine! Properly based on docs-next.

:-) :-)

WRT the build error from test robot, it looks to me like we need these
final touches:

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 8e3df5db858e..fbd8e3ae23ea 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -582,7 +582,7 @@ pdf_documents = [
 # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
 # the Docs). In a normal build, these are supplied from the Makefile via command
 # line arguments.
-kerneldoc_bin = "../tools/docs/kernel-doc.py"
+kerneldoc_bin = "../tools/docs/kernel-doc"
 kerneldoc_srctree = ".."
 
 def setup(app):
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index 2586b4d4e494..3c815b40026b 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -289,13 +289,8 @@ def setup_kfiles(app):
 
     kerneldoc_bin = app.env.config.kerneldoc_bin
 
-    if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
-        print("Using Python kernel-doc")
-        out_style = RestFormat()
-        kfiles = KernelFiles(out_style=out_style, logger=logger)
-    else:
-        print(f"Using {kerneldoc_bin}")
-
+    out_style = RestFormat()
+    kfiles = KernelFiles(out_style=out_style, logger=logger)
 
 def setup(app):
     app.add_config_value('kerneldoc_bin', None, 'env')
diff --git a/Makefile b/Makefile
index d6ff0af5cca6..33b1db1cc0cf 100644
--- a/Makefile
+++ b/Makefile
@@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
 
 # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
 # has a logic to call it
-KERNELDOC       = $(srctree)/tools/docs/kernel-doc.py
+KERNELDOC       = $(srctree)/tools/docs/kernel-doc
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \

-----------------------------------------------------------------

The change in Documentation/sphinx/kerneldoc.py is needed because

    kerneldoc_bin == ".../kernel-doc.py"

indicated loading it as python lib into the extension, while

    kerneldoc_bin == ".../kernel-doc"

indicated invoking it as a script.

Now that we don't have kernel-doc.py, loading python lib looks to me
as a natural choice.

Mauro, what do you think?

Hope this helps,
Akira

Em Sun, 26 Oct 2025 00:14:23 +0900
Akira Yokosawa <akiyks@gmail.com> escreveu:

> On Fri, 24 Oct 2025 14:08:21 -0600, Jonathan Corbet wrote:
> > Our documentation-related tools are spread out over various directories;
> > several are buried in the scripts/ dumping ground.  That makes them harder
> > to discover and harder to maintain.
> > 
> > Recent work has started accumulating our documentation-related tools in
> > /tools/docs.  This series completes that task, moving the rest of our
> > various utilities there, hopefully fixing up all of the relevant references
> > in the process.
> > 
> > At the end, rather than move the old, Perl kernel-doc, I simply removed it.
> > 
> > The big elephant lurking in this small room is the home for Python modules;
> > I left them under scripts/lib, but that is an even less appropriate place
> > than it was before.  I would propose either tools/python or lib/python;
> > thoughts on that matter welcome.
> > 
> > Changes in v3:
> >   - Now with more caffeine! Properly based on docs-next.  
> 
> :-) :-)
> 
> WRT the build error from test robot, it looks to me like we need these
> final touches:
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 8e3df5db858e..fbd8e3ae23ea 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -582,7 +582,7 @@ pdf_documents = [
>  # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
>  # the Docs). In a normal build, these are supplied from the Makefile via command
>  # line arguments.
> -kerneldoc_bin = "../tools/docs/kernel-doc.py"
> +kerneldoc_bin = "../tools/docs/kernel-doc"
>  kerneldoc_srctree = ".."
>  
>  def setup(app):
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index 2586b4d4e494..3c815b40026b 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -289,13 +289,8 @@ def setup_kfiles(app):
>  
>      kerneldoc_bin = app.env.config.kerneldoc_bin
>  
> -    if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
> -        print("Using Python kernel-doc")
> -        out_style = RestFormat()
> -        kfiles = KernelFiles(out_style=out_style, logger=logger)
> -    else:
> -        print(f"Using {kerneldoc_bin}")
> -
> +    out_style = RestFormat()
> +    kfiles = KernelFiles(out_style=out_style, logger=logger)

Patch is incomplete, as it doesn't drop the logic which forks
kernel-doc script run, but see below.

>  def setup(app):
>      app.add_config_value('kerneldoc_bin', None, 'env')
> diff --git a/Makefile b/Makefile
> index d6ff0af5cca6..33b1db1cc0cf 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
>  
>  # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
>  # has a logic to call it
> -KERNELDOC       = $(srctree)/tools/docs/kernel-doc.py
> +KERNELDOC       = $(srctree)/tools/docs/kernel-doc
>  export KERNELDOC
>  
>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
> 
> -----------------------------------------------------------------
> 
> The change in Documentation/sphinx/kerneldoc.py is needed because
> 
>     kerneldoc_bin == ".../kernel-doc.py"
> 
> indicated loading it as python lib into the extension, while
> 
>     kerneldoc_bin == ".../kernel-doc"
> 
> indicated invoking it as a script.
> 
> Now that we don't have kernel-doc.py, loading python lib looks to me
> as a natural choice.
> 
> Mauro, what do you think?

Good point. I'm not sure about this. Yeah, on normal cases, we
just want to run kernel-doc classes, instead of actually
executing its binary. Yet, for debugging purposes, it might
still be interesting to run it as separate processes.

See, right now, if KERNELDOC is not used, it will use imported
Python classes, running them directly without creating processes.
So, it won't actually call ".../kernel-doc". On such case, in
practice, it will actually ignore KERNELDOC when building docs.

Now, (after this series), if one runs:

	KERNELDOC=tools/docs/kernel-doc make htmldocs

it will run kernel-doc script as a process. This might be useful
for debugging purposes.

Also, please notice that KERNELDOC is used on several files:

	$ git grep -l KERNELDOC
	Makefile
	drivers/gpu/drm/Makefile
	drivers/gpu/drm/i915/Makefile
	include/drm/Makefile
	scripts/Makefile.build
	tools/docs/sphinx-build-wrapper

IMHO, we have some alternatives here:

1. completely drop support for KERNELDOC variable.
   On such case, we need to drop from the script:

	- kerneldoc_bin
	- run_cmd() function
	- remove KERNELDOC from Makefiles and sphinx-build-wrapper

2. keep it as is, which would help debugging (and eventually
   would allow testing two different implementations of kernel-doc
   without needing to bisect);

3. change the core of the logic to be something like:

	# kerneldoc_bin = env.config.kerneldoc_bin
	kerneldoc_bin = os.environ.get("KERNELDOC")

	if not kerneldoc_bin:
	   out_style = RestFormat()
	   kfiles = KernelFiles(out_style=out_style, logger=logger)
	else:
	    print(f"Generating C documentation by running {kerneldoc_bin} binary")

   this would still allow using KERNELDOC to point to a binary
   that will handle C files executed as a separate process.

   Please notice that the current code does:

	kerneldoc_bin = env.config.kerneldoc_bin

   This requires an extra logic at the wrapper tool, as this needs
   to be passed via -D command line option to sphinx-build. That's
   the reason why several Makefiles also use KERNELDOC env var.

   If we're willing to adopt this solution, I would simplify
   the wrapper and the makefiles to not touching KERNELDOC var
   anymore.

For (2) and (3), I would document KERNELDOC somewhere.

My personal preference would be (3), but I don't have strong
feelings.

Regards,
Mauro

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

> Patch is incomplete, as it doesn't drop the logic which forks
> kernel-doc script run, but see below.

So I clearly hadn't fully understood how this works.  Before I went and
broke things, the logic seemed to be:

  If the kerneldoc_bin environment variable is "kernel-doc.py"
  	don't actually run kernel-doc.py, build it internally instead
  else
  	run whatever program the variable points to

  ...
  set kerneldoc_bin to "kernel-doc.py" by default

This seems ... a bit obscure.  Given that:

> 3. change the core of the logic to be something like:
> 
> 	# kerneldoc_bin = env.config.kerneldoc_bin
> 	kerneldoc_bin = os.environ.get("KERNELDOC")
> 
> 	if not kerneldoc_bin:
> 	   out_style = RestFormat()
> 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
> 	else:
> 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
> 
>    this would still allow using KERNELDOC to point to a binary
>    that will handle C files executed as a separate process.

This seems like an obvious improvement, and one that, perhaps, should go
in ahead of my current series in the perhaps vain hope that we're
finally getting to the end of the list of things I can find to break...

I can send a patch around in the next couple of days if you don't beat
me to it.

jon

Em Mon, 27 Oct 2025 11:04:27 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Patch is incomplete, as it doesn't drop the logic which forks
> > kernel-doc script run, but see below.  
> 
> So I clearly hadn't fully understood how this works.  Before I went and
> broke things, the logic seemed to be:
> 
>   If the kerneldoc_bin environment variable is "kernel-doc.py"
>   	don't actually run kernel-doc.py, build it internally instead
>   else
>   	run whatever program the variable points to
> 
>   ...
>   set kerneldoc_bin to "kernel-doc.py" by default
> 
> This seems ... a bit obscure. 

Yes, but it was the best alternative I found back then :-)

Regards,
Mauro

Jonathan Corbet <corbet@lwn.net> writes:

>> 3. change the core of the logic to be something like:
>> 
>> 	# kerneldoc_bin = env.config.kerneldoc_bin
>> 	kerneldoc_bin = os.environ.get("KERNELDOC")
>> 
>> 	if not kerneldoc_bin:
>> 	   out_style = RestFormat()
>> 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
>> 	else:
>> 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
>> 
>>    this would still allow using KERNELDOC to point to a binary
>>    that will handle C files executed as a separate process.
>
> This seems like an obvious improvement, and one that, perhaps, should go
> in ahead of my current series in the perhaps vain hope that we're
> finally getting to the end of the list of things I can find to break...
>
> I can send a patch around in the next couple of days if you don't beat
> me to it.

So I have that change working just fine ... only one problem.

For this to work, we have to take out the definition of KERNELDOC in the
top-level Makefile, otherwise we'll never go the import path.  But there
are a few other Makefiles, mostly in the DRM area, that need that
definition.  So I have the docs build working, but I've broken other
things, and I think people are getting tired of me breaking things.

Possible solutions:

- Add a new FORCE_KDOC environment variable that is used instead of
  KERNELDOC to set the program to run in the docs build.

- Keep the current logic that special-cases setting KERNELDOC to
  scripts/kernel-doc.py and really runs in the imported mode in that
  case.

- Go into retirement and let it be somebody else's problem

Anybody have any other great ideas?

Thanks,

jon

Em Tue, 28 Oct 2025 17:15:26 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Jonathan Corbet <corbet@lwn.net> writes:
> 
> >> 3. change the core of the logic to be something like:
> >> 
> >> 	# kerneldoc_bin = env.config.kerneldoc_bin
> >> 	kerneldoc_bin = os.environ.get("KERNELDOC")
> >> 
> >> 	if not kerneldoc_bin:
> >> 	   out_style = RestFormat()
> >> 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
> >> 	else:
> >> 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
> >> 
> >>    this would still allow using KERNELDOC to point to a binary
> >>    that will handle C files executed as a separate process.  
> >
> > This seems like an obvious improvement, and one that, perhaps, should go
> > in ahead of my current series in the perhaps vain hope that we're
> > finally getting to the end of the list of things I can find to break...
> >
> > I can send a patch around in the next couple of days if you don't beat
> > me to it.  
> 
> So I have that change working just fine ... only one problem.
> 
> For this to work, we have to take out the definition of KERNELDOC in the
> top-level Makefile, otherwise we'll never go the import path.  But there
> are a few other Makefiles, mostly in the DRM area, that need that
> definition.

True, DRM makefiles run kernel-doc to check for warnings within the
DRM subsystem. 

>  So I have the docs build working, but I've broken other
> things, and I think people are getting tired of me breaking things.
> 
> Possible solutions:
> 
> - Add a new FORCE_KDOC environment variable that is used instead of
>   KERNELDOC to set the program to run in the docs build.

Works for me.

> - Keep the current logic that special-cases setting KERNELDOC to
>   scripts/kernel-doc.py and really runs in the imported mode in that
>   case.

Not sure if I got what you meant. Do you mean not running the classes
but always run exec() syscall? This will likely affect build time,
and prevent further speedup optimizations. It will also duplicate
warnings if we drop the output filter logic for warnings.

> 
> - Go into retirement and let it be somebody else's problem
> 
> Anybody have any other great ideas?
> 
> Thanks,
> 
> jon

On Sun, 26 Oct 2025 07:34:05 -0300, Mauro Carvalho Chehab wrote:
> Em Sun, 26 Oct 2025 00:14:23 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> On Fri, 24 Oct 2025 14:08:21 -0600, Jonathan Corbet wrote:
>>> Our documentation-related tools are spread out over various directories;
>>> several are buried in the scripts/ dumping ground.  That makes them harder
>>> to discover and harder to maintain.
>>>
>>> Recent work has started accumulating our documentation-related tools in
>>> /tools/docs.  This series completes that task, moving the rest of our
>>> various utilities there, hopefully fixing up all of the relevant references
>>> in the process.
>>>
>>> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
>>>
>>> The big elephant lurking in this small room is the home for Python modules;
>>> I left them under scripts/lib, but that is an even less appropriate place
>>> than it was before.  I would propose either tools/python or lib/python;
>>> thoughts on that matter welcome.
>>>
>>> Changes in v3:
>>>   - Now with more caffeine! Properly based on docs-next.  
>>
>> :-) :-)
>>
>> WRT the build error from test robot, it looks to me like we need these
>> final touches:
>>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 8e3df5db858e..fbd8e3ae23ea 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -582,7 +582,7 @@ pdf_documents = [
>>  # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
>>  # the Docs). In a normal build, these are supplied from the Makefile via command
>>  # line arguments.
>> -kerneldoc_bin = "../tools/docs/kernel-doc.py"
>> +kerneldoc_bin = "../tools/docs/kernel-doc"
>>  kerneldoc_srctree = ".."
>>  
>>  def setup(app):
>> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
>> index 2586b4d4e494..3c815b40026b 100644
>> --- a/Documentation/sphinx/kerneldoc.py
>> +++ b/Documentation/sphinx/kerneldoc.py
>> @@ -289,13 +289,8 @@ def setup_kfiles(app):
>>  
>>      kerneldoc_bin = app.env.config.kerneldoc_bin
>>  
>> -    if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
>> -        print("Using Python kernel-doc")
>> -        out_style = RestFormat()
>> -        kfiles = KernelFiles(out_style=out_style, logger=logger)
>> -    else:
>> -        print(f"Using {kerneldoc_bin}")
>> -
>> +    out_style = RestFormat()
>> +    kfiles = KernelFiles(out_style=out_style, logger=logger)
> 
> Patch is incomplete, as it doesn't drop the logic which forks
> kernel-doc script run, but see below.
> 
>>  def setup(app):
>>      app.add_config_value('kerneldoc_bin', None, 'env')
>> diff --git a/Makefile b/Makefile
>> index d6ff0af5cca6..33b1db1cc0cf 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
>>  
>>  # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
>>  # has a logic to call it
>> -KERNELDOC       = $(srctree)/tools/docs/kernel-doc.py
>> +KERNELDOC       = $(srctree)/tools/docs/kernel-doc
>>  export KERNELDOC
>>  
>>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
>>
>> -----------------------------------------------------------------
>>
>> The change in Documentation/sphinx/kerneldoc.py is needed because
>>
>>     kerneldoc_bin == ".../kernel-doc.py"
>>
>> indicated loading it as python lib into the extension, while
>>
>>     kerneldoc_bin == ".../kernel-doc"
>>
>> indicated invoking it as a script.
>>
>> Now that we don't have kernel-doc.py, loading python lib looks to me
>> as a natural choice.
>>
>> Mauro, what do you think?
> 
> Good point. I'm not sure about this. Yeah, on normal cases, we
> just want to run kernel-doc classes, instead of actually
> executing its binary. Yet, for debugging purposes, it might
> still be interesting to run it as separate processes.
> 
> See, right now, if KERNELDOC is not used, it will use imported
> Python classes, running them directly without creating processes.
> So, it won't actually call ".../kernel-doc". On such case, in
> practice, it will actually ignore KERNELDOC when building docs.
> 
> Now, (after this series), if one runs:
> 
> 	KERNELDOC=tools/docs/kernel-doc make htmldocs
> 
> it will run kernel-doc script as a process. This might be useful
> for debugging purposes.
> 
> Also, please notice that KERNELDOC is used on several files:
> 
> 	$ git grep -l KERNELDOC
> 	Makefile
> 	drivers/gpu/drm/Makefile
> 	drivers/gpu/drm/i915/Makefile
> 	include/drm/Makefile
> 	scripts/Makefile.build
> 	tools/docs/sphinx-build-wrapper
> 
> IMHO, we have some alternatives here:
> 
> 1. completely drop support for KERNELDOC variable.
>    On such case, we need to drop from the script:
> 
> 	- kerneldoc_bin
> 	- run_cmd() function
> 	- remove KERNELDOC from Makefiles and sphinx-build-wrapper
> 
> 2. keep it as is, which would help debugging (and eventually
>    would allow testing two different implementations of kernel-doc
>    without needing to bisect);
> 

So, as far as the build regression reported by the build bot is
concerned, I think 2. is good enough.

Probably, Jon included the rename of:

 scripts/kernel-doc                                     |  1 -
 scripts/kernel-doc.py => tools/docs/kernel-doc         |  0
 16 files changed, 22 insertions(+), 24 deletions(-)
 delete mode 120000 scripts/kernel-doc
 rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)

in 6/8 considering it the right thing to do.

Let's keep the symlink of kernel-doc --> kernel-doc.py, at least for the
time being.

Further tweaks and cleanups around KERNELDOC can wait.

       Thanks, Akira

Hi,

On 10/26/25 3:34 AM, Mauro Carvalho Chehab wrote:
> Em Sun, 26 Oct 2025 00:14:23 +0900
> Akira Yokosawa <akiyks@gmail.com> escreveu:
> 
>> On Fri, 24 Oct 2025 14:08:21 -0600, Jonathan Corbet wrote:
>>> Our documentation-related tools are spread out over various directories;
>>> several are buried in the scripts/ dumping ground.  That makes them harder
>>> to discover and harder to maintain.
>>>
>>> Recent work has started accumulating our documentation-related tools in
>>> /tools/docs.  This series completes that task, moving the rest of our
>>> various utilities there, hopefully fixing up all of the relevant references
>>> in the process.
>>>
>>> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
>>>
>>> The big elephant lurking in this small room is the home for Python modules;
>>> I left them under scripts/lib, but that is an even less appropriate place
>>> than it was before.  I would propose either tools/python or lib/python;
>>> thoughts on that matter welcome.
>>>
>>> Changes in v3:
>>>   - Now with more caffeine! Properly based on docs-next.  
>>
>> :-) :-)
>>
>> WRT the build error from test robot, it looks to me like we need these
>> final touches:
>>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 8e3df5db858e..fbd8e3ae23ea 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -582,7 +582,7 @@ pdf_documents = [
>>  # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
>>  # the Docs). In a normal build, these are supplied from the Makefile via command
>>  # line arguments.
>> -kerneldoc_bin = "../tools/docs/kernel-doc.py"
>> +kerneldoc_bin = "../tools/docs/kernel-doc"
>>  kerneldoc_srctree = ".."
>>  
>>  def setup(app):
>> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
>> index 2586b4d4e494..3c815b40026b 100644
>> --- a/Documentation/sphinx/kerneldoc.py
>> +++ b/Documentation/sphinx/kerneldoc.py
>> @@ -289,13 +289,8 @@ def setup_kfiles(app):
>>  
>>      kerneldoc_bin = app.env.config.kerneldoc_bin
>>  
>> -    if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
>> -        print("Using Python kernel-doc")
>> -        out_style = RestFormat()
>> -        kfiles = KernelFiles(out_style=out_style, logger=logger)
>> -    else:
>> -        print(f"Using {kerneldoc_bin}")
>> -
>> +    out_style = RestFormat()
>> +    kfiles = KernelFiles(out_style=out_style, logger=logger)
> 
> Patch is incomplete, as it doesn't drop the logic which forks
> kernel-doc script run, but see below.
> 
>>  def setup(app):
>>      app.add_config_value('kerneldoc_bin', None, 'env')
>> diff --git a/Makefile b/Makefile
>> index d6ff0af5cca6..33b1db1cc0cf 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
>>  
>>  # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
>>  # has a logic to call it
>> -KERNELDOC       = $(srctree)/tools/docs/kernel-doc.py
>> +KERNELDOC       = $(srctree)/tools/docs/kernel-doc
>>  export KERNELDOC
>>  
>>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
>>
>> -----------------------------------------------------------------
>>
>> The change in Documentation/sphinx/kerneldoc.py is needed because
>>
>>     kerneldoc_bin == ".../kernel-doc.py"
>>
>> indicated loading it as python lib into the extension, while
>>
>>     kerneldoc_bin == ".../kernel-doc"
>>
>> indicated invoking it as a script.
>>
>> Now that we don't have kernel-doc.py, loading python lib looks to me
>> as a natural choice.
>>
>> Mauro, what do you think?
> 
> Good point. I'm not sure about this. Yeah, on normal cases, we
> just want to run kernel-doc classes, instead of actually
> executing its binary. Yet, for debugging purposes, it might
> still be interesting to run it as separate processes.
> 
> See, right now, if KERNELDOC is not used, it will use imported
> Python classes, running them directly without creating processes.
> So, it won't actually call ".../kernel-doc". On such case, in
> practice, it will actually ignore KERNELDOC when building docs.
> 
> Now, (after this series), if one runs:
> 
> 	KERNELDOC=tools/docs/kernel-doc make htmldocs
> 
> it will run kernel-doc script as a process. This might be useful
> for debugging purposes.
> 
> Also, please notice that KERNELDOC is used on several files:
> 
> 	$ git grep -l KERNELDOC
> 	Makefile
> 	drivers/gpu/drm/Makefile
> 	drivers/gpu/drm/i915/Makefile
> 	include/drm/Makefile
> 	scripts/Makefile.build
> 	tools/docs/sphinx-build-wrapper
> 
> IMHO, we have some alternatives here:
> 
> 1. completely drop support for KERNELDOC variable.
>    On such case, we need to drop from the script:
> 
> 	- kerneldoc_bin
> 	- run_cmd() function
> 	- remove KERNELDOC from Makefiles and sphinx-build-wrapper

No, please don't drop that feature.

I'm confused by the terminology. What does "bin" or "kerneldoc_bin"
mean here?  Is there some kernel-doc binary?

> 2. keep it as is, which would help debugging (and eventually
>    would allow testing two different implementations of kernel-doc
>    without needing to bisect);
> 
> 3. change the core of the logic to be something like:
> 
> 	# kerneldoc_bin = env.config.kerneldoc_bin
> 	kerneldoc_bin = os.environ.get("KERNELDOC")
> 
> 	if not kerneldoc_bin:
> 	   out_style = RestFormat()
> 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
> 	else:
> 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
> 
>    this would still allow using KERNELDOC to point to a binary
>    that will handle C files executed as a separate process.
> 
>    Please notice that the current code does:
> 
> 	kerneldoc_bin = env.config.kerneldoc_bin
> 
>    This requires an extra logic at the wrapper tool, as this needs
>    to be passed via -D command line option to sphinx-build. That's
>    the reason why several Makefiles also use KERNELDOC env var.
> 
>    If we're willing to adopt this solution, I would simplify
>    the wrapper and the makefiles to not touching KERNELDOC var
>    anymore.
> 
> For (2) and (3), I would document KERNELDOC somewhere.
> 
> My personal preference would be (3), but I don't have strong
> feelings.


Thanks.
-- 
~Randy

Em Sun, 26 Oct 2025 14:53:32 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi,
> 
> On 10/26/25 3:34 AM, Mauro Carvalho Chehab wrote:
> > Em Sun, 26 Oct 2025 00:14:23 +0900
> > Akira Yokosawa <akiyks@gmail.com> escreveu:
> >   
> >> On Fri, 24 Oct 2025 14:08:21 -0600, Jonathan Corbet wrote:  
> >>> Our documentation-related tools are spread out over various directories;
> >>> several are buried in the scripts/ dumping ground.  That makes them harder
> >>> to discover and harder to maintain.
> >>>
> >>> Recent work has started accumulating our documentation-related tools in
> >>> /tools/docs.  This series completes that task, moving the rest of our
> >>> various utilities there, hopefully fixing up all of the relevant references
> >>> in the process.
> >>>
> >>> At the end, rather than move the old, Perl kernel-doc, I simply removed it.
> >>>
> >>> The big elephant lurking in this small room is the home for Python modules;
> >>> I left them under scripts/lib, but that is an even less appropriate place
> >>> than it was before.  I would propose either tools/python or lib/python;
> >>> thoughts on that matter welcome.
> >>>
> >>> Changes in v3:
> >>>   - Now with more caffeine! Properly based on docs-next.    
> >>
> >> :-) :-)
> >>
> >> WRT the build error from test robot, it looks to me like we need these
> >> final touches:
> >>
> >> diff --git a/Documentation/conf.py b/Documentation/conf.py
> >> index 8e3df5db858e..fbd8e3ae23ea 100644
> >> --- a/Documentation/conf.py
> >> +++ b/Documentation/conf.py
> >> @@ -582,7 +582,7 @@ pdf_documents = [
> >>  # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
> >>  # the Docs). In a normal build, these are supplied from the Makefile via command
> >>  # line arguments.
> >> -kerneldoc_bin = "../tools/docs/kernel-doc.py"
> >> +kerneldoc_bin = "../tools/docs/kernel-doc"
> >>  kerneldoc_srctree = ".."
> >>  
> >>  def setup(app):
> >> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> >> index 2586b4d4e494..3c815b40026b 100644
> >> --- a/Documentation/sphinx/kerneldoc.py
> >> +++ b/Documentation/sphinx/kerneldoc.py
> >> @@ -289,13 +289,8 @@ def setup_kfiles(app):
> >>  
> >>      kerneldoc_bin = app.env.config.kerneldoc_bin
> >>  
> >> -    if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
> >> -        print("Using Python kernel-doc")
> >> -        out_style = RestFormat()
> >> -        kfiles = KernelFiles(out_style=out_style, logger=logger)
> >> -    else:
> >> -        print(f"Using {kerneldoc_bin}")
> >> -
> >> +    out_style = RestFormat()
> >> +    kfiles = KernelFiles(out_style=out_style, logger=logger)  
> > 
> > Patch is incomplete, as it doesn't drop the logic which forks
> > kernel-doc script run, but see below.
> >   
> >>  def setup(app):
> >>      app.add_config_value('kerneldoc_bin', None, 'env')
> >> diff --git a/Makefile b/Makefile
> >> index d6ff0af5cca6..33b1db1cc0cf 100644
> >> --- a/Makefile
> >> +++ b/Makefile
> >> @@ -460,7 +460,7 @@ HOSTPKG_CONFIG	= pkg-config
> >>  
> >>  # the KERNELDOC macro needs to be exported, as scripts/Makefile.build
> >>  # has a logic to call it
> >> -KERNELDOC       = $(srctree)/tools/docs/kernel-doc.py
> >> +KERNELDOC       = $(srctree)/tools/docs/kernel-doc
> >>  export KERNELDOC
> >>  
> >>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
> >>
> >> -----------------------------------------------------------------
> >>
> >> The change in Documentation/sphinx/kerneldoc.py is needed because
> >>
> >>     kerneldoc_bin == ".../kernel-doc.py"
> >>
> >> indicated loading it as python lib into the extension, while
> >>
> >>     kerneldoc_bin == ".../kernel-doc"
> >>
> >> indicated invoking it as a script.
> >>
> >> Now that we don't have kernel-doc.py, loading python lib looks to me
> >> as a natural choice.
> >>
> >> Mauro, what do you think?  
> > 
> > Good point. I'm not sure about this. Yeah, on normal cases, we
> > just want to run kernel-doc classes, instead of actually
> > executing its binary. Yet, for debugging purposes, it might
> > still be interesting to run it as separate processes.
> > 
> > See, right now, if KERNELDOC is not used, it will use imported
> > Python classes, running them directly without creating processes.
> > So, it won't actually call ".../kernel-doc". On such case, in
> > practice, it will actually ignore KERNELDOC when building docs.
> > 
> > Now, (after this series), if one runs:
> > 
> > 	KERNELDOC=tools/docs/kernel-doc make htmldocs
> > 
> > it will run kernel-doc script as a process. This might be useful
> > for debugging purposes.
> > 
> > Also, please notice that KERNELDOC is used on several files:
> > 
> > 	$ git grep -l KERNELDOC
> > 	Makefile
> > 	drivers/gpu/drm/Makefile
> > 	drivers/gpu/drm/i915/Makefile
> > 	include/drm/Makefile
> > 	scripts/Makefile.build
> > 	tools/docs/sphinx-build-wrapper
> > 
> > IMHO, we have some alternatives here:
> > 
> > 1. completely drop support for KERNELDOC variable.
> >    On such case, we need to drop from the script:
> > 
> > 	- kerneldoc_bin
> > 	- run_cmd() function
> > 	- remove KERNELDOC from Makefiles and sphinx-build-wrapper  
> 
> No, please don't drop that feature.
> 
> I'm confused by the terminology. What does "bin" or "kerneldoc_bin"
> mean here?  Is there some kernel-doc binary?

kerneldoc_bin is the name of a variable at the Python script.
It points to KERNELDOC env.

> 
> > 2. keep it as is, which would help debugging (and eventually
> >    would allow testing two different implementations of kernel-doc
> >    without needing to bisect);
> > 
> > 3. change the core of the logic to be something like:
> > 
> > 	# kerneldoc_bin = env.config.kerneldoc_bin
> > 	kerneldoc_bin = os.environ.get("KERNELDOC")
> > 
> > 	if not kerneldoc_bin:
> > 	   out_style = RestFormat()
> > 	   kfiles = KernelFiles(out_style=out_style, logger=logger)
> > 	else:
> > 	    print(f"Generating C documentation by running {kerneldoc_bin} binary")
> > 
> >    this would still allow using KERNELDOC to point to a binary
> >    that will handle C files executed as a separate process.
> > 
> >    Please notice that the current code does:
> > 
> > 	kerneldoc_bin = env.config.kerneldoc_bin
> > 
> >    This requires an extra logic at the wrapper tool, as this needs
> >    to be passed via -D command line option to sphinx-build. That's
> >    the reason why several Makefiles also use KERNELDOC env var.
> > 
> >    If we're willing to adopt this solution, I would simplify
> >    the wrapper and the makefiles to not touching KERNELDOC var
> >    anymore.
> > 
> > For (2) and (3), I would document KERNELDOC somewhere.
> > 
> > My personal preference would be (3), but I don't have strong
> > feelings.  
> 
> 
> Thanks.

Em Fri, 24 Oct 2025 14:08:21 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Our documentation-related tools are spread out over various directories;
> several are buried in the scripts/ dumping ground.  That makes them harder
> to discover and harder to maintain.
> 
> Recent work has started accumulating our documentation-related tools in
> /tools/docs.  This series completes that task, moving the rest of our
> various utilities there, hopefully fixing up all of the relevant references
> in the process.
> 
> At the end, rather than move the old, Perl kernel-doc, I simply removed it.

LGTM.

For the entire series:

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> 
> The big elephant lurking in this small room is the home for Python modules;
> I left them under scripts/lib, but that is an even less appropriate place
> than it was before.  I would propose either tools/python or lib/python;
> thoughts on that matter welcome.

Agreed that it should be moved out of scripts/lib. Besides that,
I don't care much about its location. My personal preference would
be (with no particular order):

	- tools/python_lib
	- tools/lib_python
	- tools/lib_py
	- tools/lib

(lib/python works for me as well)

Or, if we don't aim to share code with docs and non-docs python
code, we can use:

	- tools/docs/lib

> 
> Changes in v3:
>   - Now with more caffeine! Properly based on docs-next.
> 
> Changes in v2:
>   - Rebase on top of all of Mauro's changes (the most painful rebase I've
>     ever done, I think).
>   - Land everything in /tools/docs/ rather than /tools/doc/
> 
> v2: https://lore.kernel.org/lkml/20251023161027.697135-1-corbet@lwn.net/
> v1: https://lore.kernel.org/lkml/20250813213218.198582-1-corbet@lwn.net/
> 
> 
> Jonathan Corbet (8):
>   docs: Move the "features" tools to tools/docs
>   docs: move checktransupdate.py to tools/docs
>   docs: move scripts/documentation-file-ref-check to tools/docs
>   docs: move get_abi.py to tools/docs
>   docs: move test_doc_build.py to tools/docs
>   docs: move kernel-doc to tools/docs
>   docs: move find-unused-docs.sh to tools/docs
>   docs: remove kernel-doc.pl
> 
>  Documentation/Kconfig                         |    2 +-
>  Documentation/Makefile                        |    6 +-
>  Documentation/conf.py                         |    2 +-
>  Documentation/doc-guide/checktransupdate.rst  |    6 +-
>  Documentation/doc-guide/contributing.rst      |    2 +-
>  Documentation/doc-guide/kernel-doc.rst        |    6 +-
>  Documentation/doc-guide/sphinx.rst            |    2 +-
>  Documentation/kbuild/kbuild.rst               |    2 +-
>  Documentation/process/coding-style.rst        |    2 +-
>  Documentation/sphinx/kernel_abi.py            |    2 +-
>  Documentation/sphinx/kernel_feat.py           |    4 +-
>  .../it_IT/doc-guide/kernel-doc.rst            |    8 +-
>  .../sp_SP/process/coding-style.rst            |    2 +-
>  .../zh_CN/doc-guide/checktransupdate.rst      |    6 +-
>  .../zh_CN/doc-guide/contributing.rst          |    2 +-
>  .../zh_CN/doc-guide/kernel-doc.rst            |   10 +-
>  Documentation/translations/zh_CN/how-to.rst   |    2 +-
>  .../translations/zh_CN/kbuild/kbuild.rst      |    2 +-
>  .../zh_CN/process/coding-style.rst            |    2 +-
>  .../zh_TW/process/coding-style.rst            |    2 +-
>  MAINTAINERS                                   |    5 -
>  Makefile                                      |    2 +-
>  drivers/gpu/drm/i915/Makefile                 |    2 +-
>  scripts/kernel-doc                            |    1 -
>  scripts/kernel-doc.pl                         | 2439 -----------------
>  {scripts => tools/docs}/checktransupdate.py   |    8 +-
>  .../docs}/documentation-file-ref-check        |    2 +-
>  .../docs}/features-refresh.sh                 |    0
>  {scripts => tools/docs}/find-unused-docs.sh   |    8 +-
>  {scripts => tools/docs}/get_abi.py            |    0
>  {scripts => tools/docs}/get_feat.pl           |    2 +-
>  .../kernel-doc.py => tools/docs/kernel-doc    |    0
>  .../features => tools/docs}/list-arch.sh      |    2 +-
>  tools/docs/sphinx-pre-install                 |    2 +-
>  {scripts => tools/docs}/test_doc_build.py     |    0
>  35 files changed, 50 insertions(+), 2495 deletions(-)
>  delete mode 120000 scripts/kernel-doc
>  delete mode 100755 scripts/kernel-doc.pl
>  rename {scripts => tools/docs}/checktransupdate.py (97%)
>  rename {scripts => tools/docs}/documentation-file-ref-check (99%)
>  rename {Documentation/features/scripts => tools/docs}/features-refresh.sh (100%)
>  rename {scripts => tools/docs}/find-unused-docs.sh (79%)
>  rename {scripts => tools/docs}/get_abi.py (100%)
>  rename {scripts => tools/docs}/get_feat.pl (99%)
>  rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)
>  rename {Documentation/features => tools/docs}/list-arch.sh (83%)
>  rename {scripts => tools/docs}/test_doc_build.py (100%)
>