From cb6a3e8f080063116f6c863fac3a67395e0bb1be Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Wed, 22 May 2019 09:30:46 -0700 Subject: [PATCH] doc: prepare for sphinx 2.0 upgrade Sphinx 2.0 reports some "expected errors" differently, so add the new message patterns to our known-errors scanning. Also, the kerneldoc tool has a problem with sphinx 2.0, but a fix was available. Signed-off-by: David B. Kinder --- doc/.known-issues/doc/dupdecl.conf | 2 ++ doc/extensions/kerneldoc.py | 25 ++++++++++++++++--------- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/doc/.known-issues/doc/dupdecl.conf b/doc/.known-issues/doc/dupdecl.conf index ecd0bdd3f..e086dbf65 100644 --- a/doc/.known-issues/doc/dupdecl.conf +++ b/doc/.known-issues/doc/dupdecl.conf @@ -3,3 +3,5 @@ # #^(?P[-._/\w]+/hld/hv-cpu-virt.rst):(?P[0-9]+): WARNING: Duplicate declaration. ^(?P[-._/\w]+/hld/[-._/\w]+.rst):(?P[0-9]+): WARNING: Duplicate declaration. +# Sphinx 2.0 +^(?P[-._/\w]+/hld/[-._/\w]+.rst):(?P[0-9]+): WARNING: Duplicate declaration, .* diff --git a/doc/extensions/kerneldoc.py b/doc/extensions/kerneldoc.py index fbedcc394..90d56fe7d 100644 --- a/doc/extensions/kerneldoc.py +++ b/doc/extensions/kerneldoc.py @@ -37,7 +37,10 @@ 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 +from sphinx.util.docutils import switch_source_input + +from sphinx.util import logging +logger = logging.getLogger(__name__) __version__ = '1.0' @@ -47,7 +50,7 @@ class KernelDocDirective(Directive): optional_arguments = 4 option_spec = { 'doc': directives.unchanged_required, - 'functions': directives.unchanged_required, + 'functions': directives.unchanged, 'export': directives.unchanged, 'internal': directives.unchanged, } @@ -75,8 +78,12 @@ class KernelDocDirective(Directive): elif 'doc' in self.options: cmd += ['-function', str(self.options.get('doc'))] elif 'functions' in self.options: - for f in str(self.options.get('functions')).split(): - cmd += ['-function', f] + functions = self.options.get('functions').split() + if functions: + for f in functions: + cmd += ['-function', f] + else: + cmd += ['-no-doc-sections'] for pattern in export_file_patterns: for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): @@ -86,7 +93,7 @@ class KernelDocDirective(Directive): cmd += [filename] try: - env.app.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() @@ -96,7 +103,7 @@ 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)) + 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) @@ -118,17 +125,17 @@ class KernelDocDirective(Directive): 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) + with switch_source_input(self.state, result): + 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 return node.children except Exception as e: # pylint: disable=W0703 - env.app.warn('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"))]