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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20260114204255.0140a59b@foz.lan>
Date: Wed, 14 Jan 2026 20:42:55 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, Akira Yokosawa
 <akiyks@...il.com>, Shuah Khan <shuah@...nel.org>, Jani Nikula
 <jani.nikula@...ux.intel.com>
Subject: Re: [PATCH 1/2] docs: kdoc: remove support for an external
 kernel-doc from sphinx

Em Wed, 14 Jan 2026 09:41:43 -0700
Jonathan Corbet <corbet@....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@....net>

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

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.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