Commit 24f984aa authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

docs: kdoc: remove support for an external kernel-doc from sphinx 



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.

Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <a97a8361546648906344457a7e92e4db533048a9.1768823489.git.mchehab+huawei@kernel.org>
parent 6cc45ee5

Documentation/sphinx/kerneldoc.py

+6 −47
Original line number Diff line number Diff line
@@ -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}")





def setup(app):