Re: [PATCH 1/3] docs: Sphinx: kerneldoc: only initialize kernel-doc classes once

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Jon,

Em Fri, 25 Apr 2025 15:13:38 +0800
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> Instead of re-creating the objects every time, initialize it
> just once.
> 
> This allows caching previously parsed objects.

Please notice that I opted to send you this one as you mentioned that
performance decrease when using classes.

While this patch is simple, it does improve performance and on my tests 
it is working fine, it has a potential of causing troubles. So, maybe
it could be wise to keep this on tests for a while - eventually 
postponing this one to be applied after the merge window.

Patches 2 and 3 on this series should be OK to be merged, as they
are mainly cleanups.

> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/sphinx/kerneldoc.py | 23 +++++++++++------------
>  1 file changed, 11 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index 27baf28fb754..b713a2c4a615 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -48,7 +48,8 @@ from kdoc_files import KernelFiles
>  from kdoc_output import RestFormat
>  
>  __version__  = '1.0'
> -use_kfiles = False
> +kfiles = None
> +logger = logging.getLogger('kerneldoc')
>  
>  def cmd_str(cmd):
>      """
> @@ -86,7 +87,6 @@ class KernelDocDirective(Directive):
>          'functions': directives.unchanged,
>      }
>      has_content = False
> -    logger = logging.getLogger('kerneldoc')
>      verbose = 0
>  
>      parse_args = {}
> @@ -204,7 +204,7 @@ class KernelDocDirective(Directive):
>          node = nodes.section()
>  
>          try:
> -            self.logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd)))
> +            logger.verbose("calling kernel-doc '%s'" % (" ".join(cmd)))
>  
>              p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
>              out, err = p.communicate()
> @@ -214,14 +214,14 @@ class KernelDocDirective(Directive):
>              if p.returncode != 0:
>                  sys.stderr.write(err)
>  
> -                self.logger.warning("kernel-doc '%s' failed with return code %d"
> +                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)
>  
>          except Exception as e:  # pylint: disable=W0703
> -            self.logger.warning("kernel-doc '%s' processing failed with: %s" %
> +            logger.warning("kernel-doc '%s' processing failed with: %s" %
>                                  (" ".join(cmd), str(e)))
>              return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
>  
> @@ -261,7 +261,7 @@ class KernelDocDirective(Directive):
>              self.do_parse(result, node)
>  
>          except Exception as e:  # pylint: disable=W0703
> -            self.logger.warning("kernel-doc '%s' processing failed with: %s" %
> +            logger.warning("kernel-doc '%s' processing failed with: %s" %
>                                  (cmd_str(cmd), str(e)))
>              return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
>  
> @@ -292,11 +292,9 @@ class KernelDocDirective(Directive):
>          return node.children
>  
>      def run(self):
> -        global use_kfiles
> +        global kfiles
>  
> -        if use_kfiles:
> -            out_style = RestFormat()
> -            kfiles = KernelFiles(out_style=out_style, logger=self.logger)
> +        if kfiles:
>              return self.run_kdoc(kfiles)
>          else:
>              return self.run_cmd()
> @@ -306,13 +304,14 @@ class KernelDocDirective(Directive):
>              self.state.nested_parse(result, 0, node, match_titles=1)
>  
>  def setup_kfiles(app):
> -    global use_kfiles
> +    global kfiles
>  
>      kerneldoc_bin = app.env.config.kerneldoc_bin
>  
>      if kerneldoc_bin and kerneldoc_bin.endswith("kernel-doc.py"):
>          print("Using Python kernel-doc")
> -        use_kfiles = True
> +        out_style = RestFormat()
> +        kfiles = KernelFiles(out_style=out_style, logger=logger)
>      else:
>          print(f"Using {kerneldoc_bin}")
>