diff mbox series

[v2,1/5] doc: update doc/sphinx/kerneldoc.py

Message ID 20200221172403.5358-2-xypron.glpk@gmx.de
State Accepted
Commit d94a3d17079dbf6278628686d69dc30c8e67b5b7
Delegated to: Tom Rini
Headers show
Series make htmldocs in CI | expand

Commit Message

Heinrich Schuchardt Feb. 21, 2020, 5:23 p.m. UTC 
Update doc/sphinx/kerneldoc.py from Linux next-20200219 to avoid warnings
like:

doc/sphinx/kerneldoc.py:125: RemovedInSphinx20Warning:
AutodocReporter is now deprecated. Use
sphinx.util.docutils.switch_source_input() instead.
  self.state.memo.reporter =
  	AutodocReporter(result, self.state.memo.reporter)

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
---
v2:
	new patch
---
 doc/sphinx/kerneldoc.py | 51 +++++++++++++++++++++++++++++++----------
 1 file changed, 39 insertions(+), 12 deletions(-)

--
2.25.0

Comments

Tom Rini Feb. 25, 2020, 2:07 p.m. UTC | #1 
On Fri, Feb 21, 2020 at 06:23:59PM +0100, Heinrich Schuchardt wrote:

> Update doc/sphinx/kerneldoc.py from Linux next-20200219 to avoid warnings
> like:
> 
> doc/sphinx/kerneldoc.py:125: RemovedInSphinx20Warning:
> AutodocReporter is now deprecated. Use
> sphinx.util.docutils.switch_source_input() instead.
>   self.state.memo.reporter =
>   	AutodocReporter(result, self.state.memo.reporter)
> 
> Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

Applied to u-boot/master, thanks!
diff mbox series

Patch

diff --git a/doc/sphinx/kerneldoc.py b/doc/sphinx/kerneldoc.py
index e536360de1..4bcbd6ae01 100644
--- a/doc/sphinx/kerneldoc.py
+++ b/doc/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

@@ -49,9 +59,10 @@  class KernelDocDirective(Directive):
     optional_arguments = 4
     option_spec = {
         'doc': directives.unchanged_required,
-        'functions': directives.unchanged_required,
         'export': directives.unchanged,
         'internal': directives.unchanged,
+        'identifiers': directives.unchanged,
+        'functions': directives.unchanged,
     }
     has_content = False

@@ -67,6 +78,10 @@  class KernelDocDirective(Directive):

         tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)

+        # 'function' is an alias of 'identifiers'
+        if 'functions' in self.options:
+            self.options['identifiers'] = self.options.get('functions')
+
         # FIXME: make this nicer and more robust against errors
         if 'export' in self.options:
             cmd += ['-export']
@@ -76,9 +91,13 @@  class KernelDocDirective(Directive):
             export_file_patterns = str(self.options.get('internal')).split()
         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]
+        elif 'identifiers' in self.options:
+            identifiers = self.options.get('identifiers').split()
+            if identifiers:
+                for i in identifiers:
+                    cmd += ['-function', i]
+            else:
+                cmd += ['-no-doc-sections']

         for pattern in export_file_patterns:
             for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
@@ -121,13 +140,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

@@ -136,6 +149,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')