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

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

[Jonathan Corbet]

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

[PATCH 1/2] docs: kdoc: remove support for an external kernel-doc from sphinx

[Jonathan Corbet]

The ability to build the docs with an external kernel-doc program involves
some truly confusing logic and complicates the task of moving kernel-doc
out of scripts/.  But this feature is not useful for normal documentation
builds, and the external kernel-doc can always be run by hand when it needs
debugging.  So just remove that feature and make life easier.

There is still a bunch of logic to build a command line that we never use;
the idea is to be able to output it, but I'm not sure if that is worth
keeping.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/sphinx/kerneldoc.py | 53 ++++---------------------------
 1 file changed, 6 insertions(+), 47 deletions(-)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index d8cdf068ef35c..afbab458550a8 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -190,35 +190,7 @@ class KernelDocDirective(Directive):
 
         return cmd
 
-    def run_cmd(self, cmd):
-        """
-        Execute an external kernel-doc command.
-        """
-
-        env = self.state.document.settings.env
-        node = nodes.section()
-
-        p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-        out, err = p.communicate()
-
-        out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
-
-        if p.returncode != 0:
-            sys.stderr.write(err)
-
-            logger.warning("kernel-doc '%s' failed with return code %d"
-                                % (" ".join(cmd), p.returncode))
-            return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
-        elif env.config.kerneldoc_verbosity > 0:
-            sys.stderr.write(err)
-
-        filenames = self.parse_args["file_list"]
-        for filename in filenames:
-            self.parse_msg(filename, node, out, cmd)
-
-        return node.children
-
-    def parse_msg(self, filename, node, out, cmd):
+    def parse_msg(self, filename, node, out):
         """
         Handles a kernel-doc output for a given file
         """
@@ -244,7 +216,7 @@ class KernelDocDirective(Directive):
 
         self.do_parse(result, node)
 
-    def run_kdoc(self, cmd, kfiles):
+    def run_kdoc(self, kfiles):
         """
         Execute kernel-doc classes directly instead of running as a separate
         command.
@@ -258,23 +230,17 @@ class KernelDocDirective(Directive):
         filenames = self.parse_args["file_list"]
 
         for filename, out in kfiles.msg(**self.msg_args, filenames=filenames):
-            self.parse_msg(filename, node, out, cmd)
+            self.parse_msg(filename, node, out)
 
         return node.children
 
     def run(self):
-        global kfiles
-
         cmd = self.handle_args()
         if self.verbose >= 1:
             logger.info(cmd_str(cmd))
 
         try:
-            if kfiles:
-                return self.run_kdoc(cmd, kfiles)
-            else:
-                return self.run_cmd(cmd)
-
+            return self.run_kdoc(kfiles)
         except Exception as e:  # pylint: disable=W0703
             logger.warning("kernel-doc '%s' processing failed with: %s" %
                            (cmd_str(cmd), pformat(e)))
@@ -286,15 +252,8 @@ class KernelDocDirective(Directive):
 
 def setup_kfiles(app):
     global kfiles
-
-    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):
-- 
2.52.0

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

[Jonathan Corbet]

kernel-doc is the last documentation-related tool still living outside of
the tools/docs directory; the time has come to move it over.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/conf.py                                  |  2 +-
 Documentation/doc-guide/kernel-doc.rst                 |  8 ++++----
 Documentation/kbuild/kbuild.rst                        |  2 +-
 Documentation/process/coding-style.rst                 |  2 +-
 .../translations/it_IT/doc-guide/kernel-doc.rst        |  8 ++++----
 .../translations/sp_SP/process/coding-style.rst        |  2 +-
 .../translations/zh_CN/doc-guide/kernel-doc.rst        | 10 +++++-----
 Documentation/translations/zh_CN/kbuild/kbuild.rst     |  2 +-
 .../translations/zh_CN/process/coding-style.rst        |  2 +-
 .../translations/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 +-
 scripts/kernel-doc.py => tools/docs/kernel-doc         |  0
 tools/docs/sphinx-build-wrapper                        |  2 +-
 17 files changed, 24 insertions(+), 27 deletions(-)
 delete mode 120000 scripts/kernel-doc
 rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 1ea2ae5c6276c..383d5e5b9d0af 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 = "../scripts/kernel-doc.py"
+kerneldoc_bin = "../tools/docs/kernel-doc"  # Not used now
 kerneldoc_srctree = ".."
 
 def setup(app):
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index b56128d7f5c3a..8d2c09fb36e4d 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual
 output generation may be used to verify proper formatting of the
 documentation comments. For example::
 
-	scripts/kernel-doc -v -none drivers/foo/bar.c
+	tools/docs/kernel-doc -v -none drivers/foo/bar.c
 
 The documentation format of ``.c`` files is also verified by the kernel build
 when it is requested to perform extra gcc checks::
@@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a
 left parenthesis ('(') for function-like macros or not followed by one
 for object-like macros.
 
-Function-like macros are handled like functions by ``scripts/kernel-doc``.
+Function-like macros are handled like functions by ``tools/docs/kernel-doc``.
 They may have a parameter list. Object-like macros have do not have a
 parameter list.
 
@@ -596,8 +596,8 @@ from the source file.
 
 The kernel-doc extension is included in the kernel source tree, at
 ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
-``scripts/kernel-doc`` script to extract the documentation comments from the
-source.
+``tools/docs/kernel-doc`` script to extract the documentation comments from
+the source.
 
 .. _kernel_doc:
 
diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index 82826b0332df4..5a9013bacfb75 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -180,7 +180,7 @@ architecture.
 KDOCFLAGS
 ---------
 Specify extra (warning/error) flags for kernel-doc checks during the build,
-see scripts/kernel-doc for which flags are supported. Note that this doesn't
+see tools/docs/kernel-doc for which flags are supported. Note that this doesn't
 (currently) apply to documentation builds.
 
 ARCH
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 258158637f654..35b381230f6e4 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -614,7 +614,7 @@ it.
 
 When commenting the kernel API functions, please use the kernel-doc format.
 See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
-``scripts/kernel-doc`` for details. Note that the danger of over-commenting
+``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting
 applies to kernel-doc comments all the same. Do not add boilerplate
 kernel-doc which simply reiterates what's obvious from the signature
 of the function.
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
index aa0e31d353d6f..bac959b8b7b96 100644
--- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati correttamente, potete
 eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
 che questo produca alcuna documentazione. Per esempio::
 
-	scripts/kernel-doc -v -none drivers/foo/bar.c
+	tools/docs/kernel-doc -v -none drivers/foo/bar.c
 
 Il formato della documentazione è verificato della procedura di generazione
 del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
@@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro simile a funzione sia
 immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
 oggetti no.
 
-Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
+Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kernel-doc``.
 Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
 elenco di parametri.
 
@@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*).
 
 L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
 in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
-lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
+lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazione
 dai file sorgenti.
 
 Come utilizzare kernel-doc per generare pagine man
@@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man
 Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
 farlo direttamente dai sorgenti del kernel::
 
-  $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
+  $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 025223be9706d..7d63aa8426e63 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
 
 Al comentar las funciones de la API del kernel, utilice el formato
 kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
-y ``scripts/kernel-doc`` para más detalles.
+y ``tools/docs/kernel-doc`` para más detalles.
 
 El estilo preferido para comentarios largos (de varias líneas) es:
 
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index ccfb9b8329c23..fb2bbaaa85c18 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
 用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
 是否正确。例如::
 
-	scripts/kernel-doc -v -none drivers/foo/bar.c
+	tools/docs/kernel-doc -v -none drivers/foo/bar.c
 
 当请求执行额外的gcc检查时，内核构建将验证文档格式::
 
@@ -473,7 +473,7 @@ doc: *title*
 如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
 
 kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
-在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
+在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
 
 .. _kernel_doc_zh:
 
@@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
 
 如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
 
-  $ scripts/kernel-doc -man \
+  $ tools/docs/kernel-doc -man \
     $(git grep -l '/\*\*' -- :^Documentation :^tools) \
     | scripts/split-man.pl /tmp/man
 
 一些旧版本的git不支持路径排除语法的某些变体。
 以下命令之一可能适用于这些版本::
 
-  $ scripts/kernel-doc -man \
+  $ tools/docs/kernel-doc -man \
     $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
     | scripts/split-man.pl /tmp/man
 
-  $ scripts/kernel-doc -man \
+  $ tools/docs/kernel-doc -man \
     $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
     | scripts/split-man.pl /tmp/man
 
diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst
index 57f5cf5b2cddb..a477b4b089585 100644
--- a/Documentation/translations/zh_CN/kbuild/kbuild.rst
+++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst
@@ -174,7 +174,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
 KDOCFLAGS
 ---------
 指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
-scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
+tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
 
 ARCH
 ----
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 0484d0c65c25b..5a342a024c01e 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
 也可以加上它做这些事情的原因。
 
 当注释内核 API 函数时，请使用 kernel-doc 格式。详见
-Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
+Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
 
 长 (多行) 注释的首选风格是：
 
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index 311c6f6bad0bc..e2ba97b3d8bbf 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
 也可以加上它做這些事情的原因。
 
 當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
-Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
+Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
 
 長 (多行) 註釋的首選風格是：
 
diff --git a/MAINTAINERS b/MAINTAINERS
index e03e33bd33b83..8ea68e7c2fa7a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7522,7 +7522,6 @@ S:	Maintained
 P:	Documentation/doc-guide/maintainer-profile.rst
 T:	git git://git.lwn.net/linux.git docs-next
 F:	Documentation/
-F:	scripts/kernel-doc*
 F:	tools/lib/python/*
 F:	tools/docs/
 F:	tools/net/ynl/pyynl/lib/doc_generator.py
@@ -7559,7 +7558,6 @@ M:	Mauro Carvalho Chehab <mchehab@kernel.org>
 L:	linux-doc@vger.kernel.org
 S:	Maintained
 F:	Documentation/sphinx/
-F:	scripts/kernel-doc*
 F:	tools/lib/python/*
 F:	tools/docs/
 
diff --git a/Makefile b/Makefile
index 3cd00b62cde99..81a4ab11256ce 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)/scripts/kernel-doc.py
+KERNELDOC       = $(srctree)/tools/docs/kernel-doc
 export KERNELDOC
 
 KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
index 4db24050edb0e..c979c579de66f 100644
--- a/drivers/gpu/drm/i915/Makefile
+++ b/drivers/gpu/drm/i915/Makefile
@@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
 
 quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
       cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
-		$(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
+		$(KERNELDOC) -none -Werror $<; touch $@
 
 $(obj)/%.hdrtest: $(src)/%.h FORCE
 	$(call if_changed_dep,hdrtest)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
deleted file mode 120000
index 3b6ef807791a2..0000000000000
--- a/scripts/kernel-doc
+++ /dev/null
@@ -1 +0,0 @@
-kernel-doc.py
\ No newline at end of file
diff --git a/tools/docs/find-unused-docs.sh b/tools/docs/find-unused-docs.sh
index ca4e607ec3f72..53514c759dc1b 100755
--- a/tools/docs/find-unused-docs.sh
+++ b/tools/docs/find-unused-docs.sh
@@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
 	if [[ ${FILES_INCLUDED[$file]+_} ]]; then
 	continue;
 	fi
-	str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
+	str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null)
 	if [[ -n "$str" ]]; then
 	echo "$file"
 	fi
diff --git a/scripts/kernel-doc.py b/tools/docs/kernel-doc
similarity index 100%
rename from scripts/kernel-doc.py
rename to tools/docs/kernel-doc
diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 7a5fcef254297..cb2a5005e633f 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -246,7 +246,7 @@ class SphinxBuilder:
         #
         self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
         self.kerneldoc = self.get_path(os.environ.get("KERNELDOC",
-                                                      "scripts/kernel-doc.py"))
+                                                      "tools/docs/kernel-doc"))
         self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
 
         #
-- 
2.52.0

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

[Randy Dunlap]

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

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

[Jonathan Corbet]

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

Re: [PATCH 1/2] docs: kdoc: remove support for an external kernel-doc from sphinx

[Mauro Carvalho Chehab]

Em Wed, 14 Jan 2026 09:41:43 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> The ability to build the docs with an external kernel-doc program involves
> some truly confusing logic and complicates the task of moving kernel-doc
> out of scripts/.  But this feature is not useful for normal documentation
> builds, and the external kernel-doc can always be run by hand when it needs
> debugging.  So just remove that feature and make life easier.
> 
> There is still a bunch of logic to build a command line that we never use;
> the idea is to be able to output it, but I'm not sure if that is worth
> keeping.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Agreed: it is time to get rid of such support.

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

> ---
>  Documentation/sphinx/kerneldoc.py | 53 ++++---------------------------
>  1 file changed, 6 insertions(+), 47 deletions(-)
> 
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index d8cdf068ef35c..afbab458550a8 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -190,35 +190,7 @@ class KernelDocDirective(Directive):
>  
>          return cmd
>  
> -    def run_cmd(self, cmd):
> -        """
> -        Execute an external kernel-doc command.
> -        """
> -
> -        env = self.state.document.settings.env
> -        node = nodes.section()
> -
> -        p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
> -        out, err = p.communicate()
> -
> -        out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
> -
> -        if p.returncode != 0:
> -            sys.stderr.write(err)
> -
> -            logger.warning("kernel-doc '%s' failed with return code %d"
> -                                % (" ".join(cmd), p.returncode))
> -            return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
> -        elif env.config.kerneldoc_verbosity > 0:
> -            sys.stderr.write(err)
> -
> -        filenames = self.parse_args["file_list"]
> -        for filename in filenames:
> -            self.parse_msg(filename, node, out, cmd)
> -
> -        return node.children
> -
> -    def parse_msg(self, filename, node, out, cmd):
> +    def parse_msg(self, filename, node, out):
>          """
>          Handles a kernel-doc output for a given file
>          """
> @@ -244,7 +216,7 @@ class KernelDocDirective(Directive):
>  
>          self.do_parse(result, node)
>  
> -    def run_kdoc(self, cmd, kfiles):
> +    def run_kdoc(self, kfiles):
>          """
>          Execute kernel-doc classes directly instead of running as a separate
>          command.
> @@ -258,23 +230,17 @@ class KernelDocDirective(Directive):
>          filenames = self.parse_args["file_list"]
>  
>          for filename, out in kfiles.msg(**self.msg_args, filenames=filenames):
> -            self.parse_msg(filename, node, out, cmd)
> +            self.parse_msg(filename, node, out)
>  
>          return node.children
>  
>      def run(self):
> -        global kfiles
> -
>          cmd = self.handle_args()
>          if self.verbose >= 1:
>              logger.info(cmd_str(cmd))
>  
>          try:
> -            if kfiles:
> -                return self.run_kdoc(cmd, kfiles)
> -            else:
> -                return self.run_cmd(cmd)
> -
> +            return self.run_kdoc(kfiles)
>          except Exception as e:  # pylint: disable=W0703
>              logger.warning("kernel-doc '%s' processing failed with: %s" %
>                             (cmd_str(cmd), pformat(e)))
> @@ -286,15 +252,8 @@ class KernelDocDirective(Directive):
>  
>  def setup_kfiles(app):
>      global kfiles
> -
> -    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):



Thanks,
Mauro

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

[Mauro Carvalho Chehab]

Em Wed, 14 Jan 2026 09:41:44 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> kernel-doc is the last documentation-related tool still living outside of
> the tools/docs directory; the time has come to move it over.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/conf.py                                  |  2 +-
>  Documentation/doc-guide/kernel-doc.rst                 |  8 ++++----
>  Documentation/kbuild/kbuild.rst                        |  2 +-
>  Documentation/process/coding-style.rst                 |  2 +-
>  .../translations/it_IT/doc-guide/kernel-doc.rst        |  8 ++++----
>  .../translations/sp_SP/process/coding-style.rst        |  2 +-
>  .../translations/zh_CN/doc-guide/kernel-doc.rst        | 10 +++++-----
>  Documentation/translations/zh_CN/kbuild/kbuild.rst     |  2 +-
>  .../translations/zh_CN/process/coding-style.rst        |  2 +-
>  .../translations/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 +-
>  scripts/kernel-doc.py => tools/docs/kernel-doc         |  0

Since we're doing renames anyway, why don't you call it
tools/docs/kernel_doc.py? I would prefer to stick with PEP8 names
for all python scripts as part of the coding style. 

The rationale is that Sphinx autodoc doesn't support non-PEP8 includes.
If one tries to do:

	diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
	index b56128d7f5c3..7a40b0bf36d1 100644
	--- a/Documentation/doc-guide/kernel-doc.rst
	+++ b/Documentation/doc-guide/kernel-doc.rst
	@@ -624,3 +624,11 @@ using SPHINXDIRS:
 
	    When SPHINXDIRS={subdir} is used, it will only generate man pages for
	    the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file.
	+
	+kernel\-doc module documentation
	+--------------------------------
	+
	+.. automodule:: kernel-doc
	+   :members:
	+   :show-inheritance:
	+   :undoc-members:

Sphinx refuses to document it with:

	WARNING: invalid signature for automodule ('kernel-doc') [autodoc]
	WARNING: don't know which module to import for autodocumenting 'kernel-doc' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name) [autodoc]

because of "-" instead of "_".

Doing:

	diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
	index b56128d7f5c3..666851a63af6 100644
	--- a/Documentation/doc-guide/kernel-doc.rst
	+++ b/Documentation/doc-guide/kernel-doc.rst
	@@ -624,3 +624,11 @@ using SPHINXDIRS:
 
	    When SPHINXDIRS={subdir} is used, it will only generate man pages for
	    the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file.
	+
	+kernel\-doc module documentation
	+--------------------------------
	+
	+.. automodule:: docs.kernel_doc
	+   :members:
	+   :show-inheritance:
	+   :undoc-members:
	diff --git a/scripts/kernel-doc b/scripts/kernel-doc
	deleted file mode 120000
	index 3b6ef807791a..000000000000
	--- a/scripts/kernel-doc
	+++ /dev/null
	@@ -1 +0,0 @@
	-kernel-doc.py
	\ No newline at end of file
	diff --git a/scripts/kernel-doc.py b/tools/docs/kernel_doc.py
	similarity index 100%
	rename from scripts/kernel-doc.py
	rename to tools/docs/kernel_doc.py

e.g. using underlines and ending with .py works just fine (after
applying my series adding support for sphinx.ext.autodoc.

>  tools/docs/sphinx-build-wrapper                        |  2 +-
>  17 files changed, 24 insertions(+), 27 deletions(-)
>  delete mode 120000 scripts/kernel-doc
>  rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 1ea2ae5c6276c..383d5e5b9d0af 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 = "../scripts/kernel-doc.py"
> +kerneldoc_bin = "../tools/docs/kernel-doc"  # Not used now

Better to drop it.

>  kerneldoc_srctree = ".."
>  
>  def setup(app):
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index b56128d7f5c3a..8d2c09fb36e4d 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual
>  output generation may be used to verify proper formatting of the
>  documentation comments. For example::
>  
> -	scripts/kernel-doc -v -none drivers/foo/bar.c
> +	tools/docs/kernel-doc -v -none drivers/foo/bar.c
>  
>  The documentation format of ``.c`` files is also verified by the kernel build
>  when it is requested to perform extra gcc checks::
> @@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a
>  left parenthesis ('(') for function-like macros or not followed by one
>  for object-like macros.
>  
> -Function-like macros are handled like functions by ``scripts/kernel-doc``.
> +Function-like macros are handled like functions by ``tools/docs/kernel-doc``.
>  They may have a parameter list. Object-like macros have do not have a
>  parameter list.
>  
> @@ -596,8 +596,8 @@ from the source file.
>  
>  The kernel-doc extension is included in the kernel source tree, at
>  ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
> -``scripts/kernel-doc`` script to extract the documentation comments from the
> -source.
> +``tools/docs/kernel-doc`` script to extract the documentation comments from
> +the source.
>  
>  .. _kernel_doc:
>  
> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index 82826b0332df4..5a9013bacfb75 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -180,7 +180,7 @@ architecture.
>  KDOCFLAGS
>  ---------
>  Specify extra (warning/error) flags for kernel-doc checks during the build,
> -see scripts/kernel-doc for which flags are supported. Note that this doesn't
> +see tools/docs/kernel-doc for which flags are supported. Note that this doesn't
>  (currently) apply to documentation builds.
>  
>  ARCH
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 258158637f654..35b381230f6e4 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -614,7 +614,7 @@ it.
>  
>  When commenting the kernel API functions, please use the kernel-doc format.
>  See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
> -``scripts/kernel-doc`` for details. Note that the danger of over-commenting
> +``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting
>  applies to kernel-doc comments all the same. Do not add boilerplate
>  kernel-doc which simply reiterates what's obvious from the signature
>  of the function.
> diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> index aa0e31d353d6f..bac959b8b7b96 100644
> --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
> @@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati correttamente, potete
>  eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
>  che questo produca alcuna documentazione. Per esempio::
>  
> -	scripts/kernel-doc -v -none drivers/foo/bar.c
> +	tools/docs/kernel-doc -v -none drivers/foo/bar.c
>  
>  Il formato della documentazione è verificato della procedura di generazione
>  del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
> @@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro simile a funzione sia
>  immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
>  oggetti no.
>  
> -Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
> +Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kernel-doc``.
>  Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
>  elenco di parametri.
>  
> @@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*).
>  
>  L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
>  in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
> -lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
> +lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazione
>  dai file sorgenti.
>  
>  Come utilizzare kernel-doc per generare pagine man
> @@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man
>  Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
>  farlo direttamente dai sorgenti del kernel::
>  
> -  $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
> +  $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
> diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
> index 025223be9706d..7d63aa8426e63 100644
> --- a/Documentation/translations/sp_SP/process/coding-style.rst
> +++ b/Documentation/translations/sp_SP/process/coding-style.rst
> @@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
>  
>  Al comentar las funciones de la API del kernel, utilice el formato
>  kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
> -y ``scripts/kernel-doc`` para más detalles.
> +y ``tools/docs/kernel-doc`` para más detalles.
>  
>  El estilo preferido para comentarios largos (de varias líneas) es:
>  
> diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> index ccfb9b8329c23..fb2bbaaa85c18 100644
> --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
> @@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
>  用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
>  是否正确。例如::
>  
> -	scripts/kernel-doc -v -none drivers/foo/bar.c
> +	tools/docs/kernel-doc -v -none drivers/foo/bar.c
>  
>  当请求执行额外的gcc检查时，内核构建将验证文档格式::
>  
> @@ -473,7 +473,7 @@ doc: *title*
>  如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
>  
>  kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
> -在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
> +在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
>  
>  .. _kernel_doc_zh:
>  
> @@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
>  
>  如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
>  
> -  $ scripts/kernel-doc -man \
> +  $ tools/docs/kernel-doc -man \
>      $(git grep -l '/\*\*' -- :^Documentation :^tools) \
>      | scripts/split-man.pl /tmp/man
>  
>  一些旧版本的git不支持路径排除语法的某些变体。
>  以下命令之一可能适用于这些版本::
>  
> -  $ scripts/kernel-doc -man \
> +  $ tools/docs/kernel-doc -man \
>      $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
>      | scripts/split-man.pl /tmp/man
>  
> -  $ scripts/kernel-doc -man \
> +  $ tools/docs/kernel-doc -man \
>      $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
>      | scripts/split-man.pl /tmp/man
>  
> diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst
> index 57f5cf5b2cddb..a477b4b089585 100644
> --- a/Documentation/translations/zh_CN/kbuild/kbuild.rst
> +++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst
> @@ -174,7 +174,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
>  KDOCFLAGS
>  ---------
>  指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
> -scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
> +tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
>  
>  ARCH
>  ----
> diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
> index 0484d0c65c25b..5a342a024c01e 100644
> --- a/Documentation/translations/zh_CN/process/coding-style.rst
> +++ b/Documentation/translations/zh_CN/process/coding-style.rst
> @@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
>  也可以加上它做这些事情的原因。
>  
>  当注释内核 API 函数时，请使用 kernel-doc 格式。详见
> -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
> +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
>  
>  长 (多行) 注释的首选风格是：
>  
> diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
> index 311c6f6bad0bc..e2ba97b3d8bbf 100644
> --- a/Documentation/translations/zh_TW/process/coding-style.rst
> +++ b/Documentation/translations/zh_TW/process/coding-style.rst
> @@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
>  也可以加上它做這些事情的原因。
>  
>  當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
> -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
> +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
>  
>  長 (多行) 註釋的首選風格是：
>  
> diff --git a/MAINTAINERS b/MAINTAINERS
> index e03e33bd33b83..8ea68e7c2fa7a 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -7522,7 +7522,6 @@ S:	Maintained
>  P:	Documentation/doc-guide/maintainer-profile.rst
>  T:	git git://git.lwn.net/linux.git docs-next
>  F:	Documentation/
> -F:	scripts/kernel-doc*
>  F:	tools/lib/python/*
>  F:	tools/docs/
>  F:	tools/net/ynl/pyynl/lib/doc_generator.py
> @@ -7559,7 +7558,6 @@ M:	Mauro Carvalho Chehab <mchehab@kernel.org>
>  L:	linux-doc@vger.kernel.org
>  S:	Maintained
>  F:	Documentation/sphinx/
> -F:	scripts/kernel-doc*
>  F:	tools/lib/python/*
>  F:	tools/docs/
>  
> diff --git a/Makefile b/Makefile
> index 3cd00b62cde99..81a4ab11256ce 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)/scripts/kernel-doc.py
> +KERNELDOC       = $(srctree)/tools/docs/kernel-doc
>  export KERNELDOC
>  
>  KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
> diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile
> index 4db24050edb0e..c979c579de66f 100644
> --- a/drivers/gpu/drm/i915/Makefile
> +++ b/drivers/gpu/drm/i915/Makefile
> @@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
>  
>  quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
>        cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
> -		$(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
> +		$(KERNELDOC) -none -Werror $<; touch $@
>  
>  $(obj)/%.hdrtest: $(src)/%.h FORCE
>  	$(call if_changed_dep,hdrtest)
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> deleted file mode 120000
> index 3b6ef807791a2..0000000000000
> --- a/scripts/kernel-doc
> +++ /dev/null
> @@ -1 +0,0 @@
> -kernel-doc.py
> \ No newline at end of file
> diff --git a/tools/docs/find-unused-docs.sh b/tools/docs/find-unused-docs.sh
> index ca4e607ec3f72..53514c759dc1b 100755
> --- a/tools/docs/find-unused-docs.sh
> +++ b/tools/docs/find-unused-docs.sh
> @@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
>  	if [[ ${FILES_INCLUDED[$file]+_} ]]; then
>  	continue;
>  	fi
> -	str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
> +	str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null)
>  	if [[ -n "$str" ]]; then
>  	echo "$file"
>  	fi
> diff --git a/scripts/kernel-doc.py b/tools/docs/kernel-doc
> similarity index 100%
> rename from scripts/kernel-doc.py
> rename to tools/docs/kernel-doc
> diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> index 7a5fcef254297..cb2a5005e633f 100755
> --- a/tools/docs/sphinx-build-wrapper
> +++ b/tools/docs/sphinx-build-wrapper
> @@ -246,7 +246,7 @@ class SphinxBuilder:
>          #
>          self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
>          self.kerneldoc = self.get_path(os.environ.get("KERNELDOC",
> -                                                      "scripts/kernel-doc.py"))
> +                                                      "tools/docs/kernel-doc"))
>          self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
>  
>          #



Thanks,
Mauro

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

[Mauro Carvalho Chehab]

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

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

[Jani Nikula]

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

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

[Mauro Carvalho Chehab]

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

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

[Jani Nikula]

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

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

[Jonathan Corbet]

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

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

[Randy Dunlap]

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

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

[Jonathan Corbet]

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

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

[Randy Dunlap]

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

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

[Jani Nikula]

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

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

[Jonathan Corbet]

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

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

[Jonathan Corbet]

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

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

[Mauro Carvalho Chehab]

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

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

[Mauro Carvalho Chehab]

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

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

[Randy Dunlap]

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

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

[kernel test robot]

Hi Jonathan,

kernel test robot noticed the following build errors:

[auto build test ERROR on lwn/docs-next]
[also build test ERROR on drm-i915/for-linux-next drm-i915/for-linux-next-fixes linus/master v6.19-rc6 next-20260116]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Jonathan-Corbet/docs-kdoc-remove-support-for-an-external-kernel-doc-from-sphinx/20260115-004646
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20260114164146.532916-3-corbet%40lwn.net
patch subject: [PATCH 2/2] Move kernel-doc to tools/docs
config: x86_64-kexec (https://download.01.org/0day-ci/archive/20260119/202601191546.Bvd74asP-lkp@intel.com/config)
compiler: clang version 20.1.8 (https://github.com/llvm/llvm-project 87f0227cb60147a26a1eeb4fb06e3b505e9c7261)
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260119/202601191546.Bvd74asP-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202601191546.Bvd74asP-lkp@intel.com/

All errors (new ones prefixed by >>):

   Traceback (most recent call last):
     File "tools/docs/kernel-doc", line 339, in <module>
       main()
       ~~~~^^
     File "tools/docs/kernel-doc", line 295, in main
       from kdoc.kdoc_files import KernelFiles             # pylint: disable=C0415
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> ModuleNotFoundError: No module named 'kdoc'
   make[3]: *** [scripts/Makefile.build:287: scripts/mod/empty.o] Error 1
   make[3]: *** Deleting file 'scripts/mod/empty.o'
   make[3]: Target 'scripts/mod/' not remade because of errors.
   make[2]: *** [Makefile:1313: prepare0] Error 2
   make[2]: Target 'prepare' not remade because of errors.
   make[1]: *** [Makefile:248: __sub-make] Error 2
   make[1]: Target 'prepare' not remade because of errors.
   make: *** [Makefile:248: __sub-make] Error 2
   make: Target 'prepare' not remade because of errors.

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

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

[Mauro Carvalho Chehab]

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

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

[Mauro Carvalho Chehab]

Em Wed, 14 Jan 2026 09:41:44 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> kernel-doc is the last documentation-related tool still living outside of
> the tools/docs directory; the time has come to move it over.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

...

> diff --git a/scripts/kernel-doc.py b/tools/docs/kernel-doc
> similarity index 100%
> rename from scripts/kernel-doc.py
> rename to tools/docs/kernel-doc

As reported by kernel test robot:
	 https://lore.kernel.org/linux-doc/202601191546.Bvd74asP-lkp@intel.com/

Here, you also need to change the relative location of the modules:

	 # Import Python modules

	-LIB_DIR = "../tools/lib/python"
	+LIB_DIR = "../lib/python"
	 SRC_DIR = os.path.dirname(os.path.realpath(__file__))

	 sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))

Thanks,
Mauro