diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-29 14:36:41 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2019-05-29 14:36:41 -0700 |
commit | bec7550cca106c3ccc061e3e625516af63054fe4 (patch) | |
tree | 2b53e2cb496c0159a4862a91ca2b7f83c562e4df /Documentation/sphinx/kerneldoc.py | |
parent | 2b28601d62b01429d12e999fe3712aaf57ca2e26 (diff) | |
parent | 551bd3368a7b3cfef01edaade8970948d178d40a (diff) |
Merge tag 'docs-5.2-fixes2' of git://git.lwn.net/linux
Pull documentation fixes from Jonathan Corbet:
"The Sphinx 2.0 release contained a few incompatible API changes that
broke our extensions and, thus, the documentation build in general.
Who knew that those deprecation warnings it was outputting actually
meant we should change something? This set of fixes makes the build
work again with Sphinx 2.0 and eliminates the warnings for 1.8. As
part of that, we also need a few fixes to the docs for places where
the new Sphinx is more strict.
It is a bit late in the cycle for this kind of change, but it does fix
problems that people are experiencing now.
There has been some talk of raising the minimum version of Sphinx we
support. I don't want to do that abruptly, though, so these changes
add some glue to continue to support versions back to 1.3. We will be
adding some infrastructure soon to nudge users of old versions
forward, with the idea of maybe increasing our minimum version (and
removing this glue) sometime in the future"
* tag 'docs-5.2-fixes2' of git://git.lwn.net/linux:
drm/i915: Maintain consistent documentation subsection ordering
scripts/sphinx-pre-install: make it handle Sphinx versions
docs: Fix conf.py for Sphinx 2.0
docs: fix multiple doc build warnings in enumeration.rst
lib/list_sort: fix kerneldoc build error
docs: fix numaperf.rst and add it to the doc tree
doc: Cope with the deprecation of AutoReporter
doc: Cope with Sphinx logging deprecations
Diffstat (limited to 'Documentation/sphinx/kerneldoc.py')
-rw-r--r-- | Documentation/sphinx/kerneldoc.py | 44 |
1 files changed, 33 insertions, 11 deletions
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 9d0a7f08f93b..1159405cb920 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -37,7 +37,19 @@ 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 __version__ = '1.0' @@ -90,7 +102,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 +113,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) @@ -121,20 +135,28 @@ class KernelDocDirective(Directive): lineoffset += 1 node = nodes.section() - buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.do_parse(result, node) + + return node.children + + except Exception as e: # pylint: disable=W0703 + 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 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 = buf + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save - return node.children - - except Exception as e: # pylint: disable=W0703 - env.app.warn('kernel-doc \'%s\' processing failed with: %s' % - (" ".join(cmd), str(e))) - return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] def setup(app): app.add_config_value('kerneldoc_bin', None, 'env') |