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.0Em 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
© 2016 - 2026 Red Hat, Inc.