queue-4.14/doc-cope-with-sphinx-logging-deprecations.patch

   1 From 096ea522e84ea68f8e6c41e5e7294731a81e29bc Mon Sep 17 00:00:00 2001
   2 From: Jonathan Corbet <corbet@lwn.net>
   3 Date: Tue, 21 May 2019 14:23:43 -0600
   4 Subject: doc: Cope with Sphinx logging deprecations
   5
   6 From: Jonathan Corbet <corbet@lwn.net>
   7
   8 commit 096ea522e84ea68f8e6c41e5e7294731a81e29bc upstream.
   9
  10 Recent versions of sphinx will emit messages like:
  11
  12   Documentation/sphinx/kerneldoc.py:103:
  13      RemovedInSphinx20Warning: app.warning() is now deprecated.
  14      Use sphinx.util.logging instead.
  15
  16 Switch to sphinx.util.logging to make this unsightly message go away.
  17 Alas, that interface was only added in version 1.6, so we have to add a
  18 version check to keep things working with older sphinxes.
  19
  20 Cc: stable@vger.kernel.org
  21 Signed-off-by: Jonathan Corbet <corbet@lwn.net>
  22 Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
  23
  24 ---
  25  Documentation/sphinx/kerneldoc.py |   12 +++++++----
  26  Documentation/sphinx/kernellog.py |   28 ++++++++++++++++++++++++++
  27  Documentation/sphinx/kfigure.py   |   40 +++++++++++++++++++++-----------------
  28  3 files changed, 59 insertions(+), 21 deletions(-)
  29
  30 --- a/Documentation/sphinx/kerneldoc.py
  31 +++ b/Documentation/sphinx/kerneldoc.py
  32 @@ -49,6 +49,8 @@ if Use_SSI:
  33  else:
  34      from sphinx.ext.autodoc import AutodocReporter
  35
  36 +import kernellog
  37 +
  38  __version__  = '1.0'
  39
  40  class KernelDocDirective(Directive):
  41 @@ -96,7 +98,8 @@ class KernelDocDirective(Directive):
  42          cmd += [filename]
  43
  44          try:
  45 -            env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
  46 +            kernellog.verbose(env.app,
  47 +                              'calling kernel-doc \'%s\'' % (" ".join(cmd)))
  48
  49              p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
  50              out, err = p.communicate()
  51 @@ -106,7 +109,8 @@ class KernelDocDirective(Directive):
  52              if p.returncode != 0:
  53                  sys.stderr.write(err)
  54
  55 -                env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
  56 +                kernellog.warn(env.app,
  57 +                               'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
  58                  return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
  59              elif env.config.kerneldoc_verbosity > 0:
  60                  sys.stderr.write(err)
  61 @@ -132,8 +136,8 @@ class KernelDocDirective(Directive):
  62              return node.children
  63
  64          except Exception as e:  # pylint: disable=W0703
  65 -            env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
  66 -                         (" ".join(cmd), str(e)))
  67 +            kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' %
  68 +                           (" ".join(cmd), str(e)))
  69              return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
  70
  71      def do_parse(self, result, node):
  72 --- /dev/null
  73 +++ b/Documentation/sphinx/kernellog.py
  74 @@ -0,0 +1,28 @@
  75 +# SPDX-License-Identifier: GPL-2.0
  76 +#
  77 +# Sphinx has deprecated its older logging interface, but the replacement
  78 +# only goes back to 1.6.  So here's a wrapper layer to keep around for
  79 +# as long as we support 1.4.
  80 +#
  81 +import sphinx
  82 +
  83 +if sphinx.__version__[:3] >= '1.6':
  84 +    UseLogging = True
  85 +    from sphinx.util import logging
  86 +    logger = logging.getLogger('kerneldoc')
  87 +else:
  88 +    UseLogging = False
  89 +
  90 +def warn(app, message):
  91 +    if UseLogging:
  92 +        logger.warning(message)
  93 +    else:
  94 +        app.warn(message)
  95 +
  96 +def verbose(app, message):
  97 +    if UseLogging:
  98 +        logger.verbose(message)
  99 +    else:
 100 +        app.verbose(message)
 101 +
 102 +
 103 --- a/Documentation/sphinx/kfigure.py
 104 +++ b/Documentation/sphinx/kfigure.py
 105 @@ -60,6 +60,8 @@ import sphinx
 106  from sphinx.util.nodes import clean_astext
 107  from six import iteritems
 108
 109 +import kernellog
 110 +
 111  PY3 = sys.version_info[0] == 3
 112
 113  if PY3:
 114 @@ -171,20 +173,20 @@ def setupTools(app):
 115      This function is called once, when the builder is initiated.
 116      """
 117      global dot_cmd, convert_cmd   # pylint: disable=W0603
 118 -    app.verbose("kfigure: check installed tools ...")
 119 +    kernellog.verbose(app, "kfigure: check installed tools ...")
 120
 121      dot_cmd = which('dot')
 122      convert_cmd = which('convert')
 123
 124      if dot_cmd:
 125 -        app.verbose("use dot(1) from: " + dot_cmd)
 126 +        kernellog.verbose(app, "use dot(1) from: " + dot_cmd)
 127      else:
 128 -        app.warn("dot(1) not found, for better output quality install "
 129 -                 "graphviz from http://www.graphviz.org")
 130 +        kernellog.warn(app, "dot(1) not found, for better output quality install "
 131 +                       "graphviz from http://www.graphviz.org")
 132      if convert_cmd:
 133 -        app.verbose("use convert(1) from: " + convert_cmd)
 134 +        kernellog.verbose(app, "use convert(1) from: " + convert_cmd)
 135      else:
 136 -        app.warn(
 137 +        kernellog.warn(app,
 138              "convert(1) not found, for SVG to PDF conversion install "
 139              "ImageMagick (https://www.imagemagick.org)")
 140
 141 @@ -220,12 +222,13 @@ def convert_image(img_node, translator,
 142
 143      # in kernel builds, use 'make SPHINXOPTS=-v' to see verbose messages
 144
 145 -    app.verbose('assert best format for: ' + img_node['uri'])
 146 +    kernellog.verbose(app, 'assert best format for: ' + img_node['uri'])
 147
 148      if in_ext == '.dot':
 149
 150          if not dot_cmd:
 151 -            app.verbose("dot from graphviz not available / include DOT raw.")
 152 +            kernellog.verbose(app,
 153 +                              "dot from graphviz not available / include DOT raw.")
 154              img_node.replace_self(file2literal(src_fname))
 155
 156          elif translator.builder.format == 'latex':
 157 @@ -252,7 +255,8 @@ def convert_image(img_node, translator,
 158
 159          if translator.builder.format == 'latex':
 160              if convert_cmd is None:
 161 -                app.verbose("no SVG to PDF conversion available / include SVG raw.")
 162 +                kernellog.verbose(app,
 163 +                                  "no SVG to PDF conversion available / include SVG raw.")
 164                  img_node.replace_self(file2literal(src_fname))
 165              else:
 166                  dst_fname = path.join(translator.builder.outdir, fname + '.pdf')
 167 @@ -265,18 +269,19 @@ def convert_image(img_node, translator,
 168          _name = dst_fname[len(translator.builder.outdir) + 1:]
 169
 170          if isNewer(dst_fname, src_fname):
 171 -            app.verbose("convert: {out}/%s already exists and is newer" % _name)
 172 +            kernellog.verbose(app,
 173 +                              "convert: {out}/%s already exists and is newer" % _name)
 174
 175          else:
 176              ok = False
 177              mkdir(path.dirname(dst_fname))
 178
 179              if in_ext == '.dot':
 180 -                app.verbose('convert DOT to: {out}/' + _name)
 181 +                kernellog.verbose(app, 'convert DOT to: {out}/' + _name)
 182                  ok = dot2format(app, src_fname, dst_fname)
 183
 184              elif in_ext == '.svg':
 185 -                app.verbose('convert SVG to: {out}/' + _name)
 186 +                kernellog.verbose(app, 'convert SVG to: {out}/' + _name)
 187                  ok = svg2pdf(app, src_fname, dst_fname)
 188
 189              if not ok:
 190 @@ -305,7 +310,8 @@ def dot2format(app, dot_fname, out_fname
 191      with open(out_fname, "w") as out:
 192          exit_code = subprocess.call(cmd, stdout = out)
 193          if exit_code != 0:
 194 -            app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
 195 +            kernellog.warn(app,
 196 +                          "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
 197      return bool(exit_code == 0)
 198
 199  def svg2pdf(app, svg_fname, pdf_fname):
 200 @@ -322,7 +328,7 @@ def svg2pdf(app, svg_fname, pdf_fname):
 201      # use stdout and stderr from parent
 202      exit_code = subprocess.call(cmd)
 203      if exit_code != 0:
 204 -        app.warn("Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
 205 +        kernellog.warn(app, "Error #%d when calling: %s" % (exit_code, " ".join(cmd)))
 206      return bool(exit_code == 0)
 207
 208
 209 @@ -415,15 +421,15 @@ def visit_kernel_render(self, node):
 210      app = self.builder.app
 211      srclang = node.get('srclang')
 212
 213 -    app.verbose('visit kernel-render node lang: "%s"' % (srclang))
 214 +    kernellog.verbose('visit kernel-render node lang: "%s"' % (srclang))
 215
 216      tmp_ext = RENDER_MARKUP_EXT.get(srclang, None)
 217      if tmp_ext is None:
 218 -        app.warn('kernel-render: "%s" unknow / include raw.' % (srclang))
 219 +        kernellog.warn('kernel-render: "%s" unknow / include raw.' % (srclang))
 220          return
 221
 222      if not dot_cmd and tmp_ext == '.dot':
 223 -        app.verbose("dot from graphviz not available / include raw.")
 224 +        kernellog.verbose("dot from graphviz not available / include raw.")
 225          return
 226
 227      literal_block = node[0]