queue-4.19/doc-cope-with-the-deprecation-of-autoreporter.patch

   1 From 2404dad1f67f8917e30fc22a85e0dbcc85b99955 Mon Sep 17 00:00:00 2001
   2 From: Jonathan Corbet <corbet@lwn.net>
   3 Date: Tue, 21 May 2019 14:42:34 -0600
   4 Subject: doc: Cope with the deprecation of AutoReporter
   5
   6 From: Jonathan Corbet <corbet@lwn.net>
   7
   8 commit 2404dad1f67f8917e30fc22a85e0dbcc85b99955 upstream.
   9
  10 AutoReporter is going away; recent versions of sphinx emit a warning like:
  11
  12   Documentation/sphinx/kerneldoc.py:125:
  13       RemovedInSphinx20Warning: AutodocReporter is now deprecated.
  14       Use sphinx.util.docutils.switch_source_input() instead.
  15
  16 Make the switch.  But switch_source_input() only showed up in 1.7, so we
  17 have to do ugly version checks to keep things working in older versions.
  18
  19 Cc: stable@vger.kernel.org
  20 Signed-off-by: Jonathan Corbet <corbet@lwn.net>
  21 Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
  22
  23 ---
  24  Documentation/sphinx/kerneldoc.py |   34 ++++++++++++++++++++++++++--------
  25  1 file changed, 26 insertions(+), 8 deletions(-)
  26
  27 --- a/Documentation/sphinx/kerneldoc.py
  28 +++ b/Documentation/sphinx/kerneldoc.py
  29 @@ -37,7 +37,17 @@ import glob
  30  from docutils import nodes, statemachine
  31  from docutils.statemachine import ViewList
  32  from docutils.parsers.rst import directives, Directive
  33 -from sphinx.ext.autodoc import AutodocReporter
  34 +
  35 +#
  36 +# AutodocReporter is only good up to Sphinx 1.7
  37 +#
  38 +import sphinx
  39 +
  40 +Use_SSI = sphinx.__version__[:3] >= '1.7'
  41 +if Use_SSI:
  42 +    from sphinx.util.docutils import switch_source_input
  43 +else:
  44 +    from sphinx.ext.autodoc import AutodocReporter
  45
  46  __version__  = '1.0'
  47
  48 @@ -121,13 +131,7 @@ class KernelDocDirective(Directive):
  49                      lineoffset += 1
  50
  51              node = nodes.section()
  52 -            buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
  53 -            self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
  54 -            self.state.memo.title_styles, self.state.memo.section_level = [], 0
  55 -            try:
  56 -                self.state.nested_parse(result, 0, node, match_titles=1)
  57 -            finally:
  58 -                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
  59 +            self.do_parse(result, node)
  60
  61              return node.children
  62
  63 @@ -136,6 +140,20 @@ class KernelDocDirective(Directive):
  64                           (" ".join(cmd), str(e)))
  65              return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
  66
  67 +    def do_parse(self, result, node):
  68 +        if Use_SSI:
  69 +            with switch_source_input(self.state, result):
  70 +                self.state.nested_parse(result, 0, node, match_titles=1)
  71 +        else:
  72 +            save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
  73 +            self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
  74 +            self.state.memo.title_styles, self.state.memo.section_level = [], 0
  75 +            try:
  76 +                self.state.nested_parse(result, 0, node, match_titles=1)
  77 +            finally:
  78 +                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save
  79 +
  80 +
  81  def setup(app):
  82      app.add_config_value('kerneldoc_bin', None, 'env')
  83      app.add_config_value('kerneldoc_srctree', None, 'env')