From 096ea522e84ea68f8e6c41e5e7294731a81e29bc Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 21 May 2019 14:23:43 -0600 Subject: doc: Cope with Sphinx logging deprecations Recent versions of sphinx will emit messages like: Documentation/sphinx/kerneldoc.py:103: RemovedInSphinx20Warning: app.warning() is now deprecated. Use sphinx.util.logging instead. Switch to sphinx.util.logging to make this unsightly message go away. Alas, that interface was only added in version 1.6, so we have to add a version check to keep things working with older sphinxes. Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kerneldoc.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'Documentation/sphinx/kerneldoc.py') diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 9d0a7f08f93b..200c8aa4a04f 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -39,6 +39,8 @@ from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive from sphinx.ext.autodoc import AutodocReporter +import kernellog + __version__ = '1.0' class KernelDocDirective(Directive): @@ -90,7 +92,8 @@ class KernelDocDirective(Directive): cmd += [filename] try: - env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) + kernellog.verbose(env.app, + 'calling kernel-doc \'%s\'' % (" ".join(cmd))) p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) out, err = p.communicate() @@ -100,7 +103,8 @@ class KernelDocDirective(Directive): if p.returncode != 0: sys.stderr.write(err) - env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + kernellog.warn(env.app, + '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) @@ -132,8 +136,8 @@ class KernelDocDirective(Directive): return node.children except Exception as e: # pylint: disable=W0703 - env.app.warn('kernel-doc \'%s\' processing failed with: %s' % - (" ".join(cmd), str(e))) + kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] def setup(app): -- cgit v1.2.3 From 2404dad1f67f8917e30fc22a85e0dbcc85b99955 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 21 May 2019 14:42:34 -0600 Subject: doc: Cope with the deprecation of AutoReporter AutoReporter is going away; recent versions of sphinx emit a warning like: Documentation/sphinx/kerneldoc.py:125: RemovedInSphinx20Warning: AutodocReporter is now deprecated. Use sphinx.util.docutils.switch_source_input() instead. Make the switch. But switch_source_input() only showed up in 1.7, so we have to do ugly version checks to keep things working in older versions. Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet --- Documentation/sphinx/kerneldoc.py | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) (limited to 'Documentation/sphinx/kerneldoc.py') diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 200c8aa4a04f..1159405cb920 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -37,7 +37,17 @@ import glob from docutils import nodes, statemachine from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive -from sphinx.ext.autodoc import AutodocReporter + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter import kernellog @@ -125,13 +135,7 @@ class KernelDocDirective(Directive): lineoffset += 1 node = nodes.section() - buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter - self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) - self.state.memo.title_styles, self.state.memo.section_level = [], 0 - try: - self.state.nested_parse(result, 0, node, match_titles=1) - finally: - self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + self.do_parse(result, node) return node.children @@ -140,6 +144,20 @@ class KernelDocDirective(Directive): (" ".join(cmd), str(e))) return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + def do_parse(self, result, node): + if Use_SSI: + with switch_source_input(self.state, result): + self.state.nested_parse(result, 0, node, match_titles=1) + else: + save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save + + def setup(app): app.add_config_value('kerneldoc_bin', None, 'env') app.add_config_value('kerneldoc_srctree', None, 'env') -- cgit v1.2.3