| Message ID | 20190521211714.1395-3-corbet@lwn.net |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: Deal with some Sphinx deprecation warnings | expand |
On Tue, 21 May 2019, Jonathan Corbet <corbet@lwn.net> wrote: > AutoReporter is going away; recent versions of sphinx emit a warning like: > > /stuff/k/git/kernel/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. > --- > Documentation/sphinx/kerneldoc.py | 38 ++++++++++++++++++++++++------- > 1 file changed, 30 insertions(+), 8 deletions(-) > > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py > index e8891e63e001..d3216f7b4170 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,24 @@ 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: > + save = self.state.memo.title_styles, self.state.memo.section_level > + try: > + with switch_source_input(self.state, result): > + self.state.nested_parse(result, 0, node, match_titles=1) IIUC you don't need to save the state anymore, so the above two lines should be sufficient when using switch_source_input. BR, Jani. > + finally: > + self.state.memo.title_styles, self.state.memo.section_level = save > + 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') -- Jani Nikula, Intel Open Source Graphics Center
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index e8891e63e001..d3216f7b4170 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,24 @@ 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: + save = self.state.memo.title_styles, self.state.memo.section_level + try: + 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 = save + 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')
AutoReporter is going away; recent versions of sphinx emit a warning like: /stuff/k/git/kernel/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. --- Documentation/sphinx/kerneldoc.py | 38 ++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 8 deletions(-) -- 2.21.0