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(-)

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') -- 2.25.0

Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI.

Provide a build step for 'make htmldocs'.

Add required package graphviz.

Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de --- v2: change sequence of targets: put htmldocs after cppcheck --- .travis.yml | 5 +++++ 1 file changed, 5 insertions(+)

diff --git a/.travis.yml b/.travis.yml index e6db9d6a72..911c85e130 100644 --- a/.travis.yml +++ b/.travis.yml @@ -38,6 +38,7 @@ addons: - libisl15 - clang-7 - srecord + - graphviz

install: # Clone uboot-test-hooks @@ -352,6 +353,10 @@ matrix: - name: "cppcheck" script: - cppcheck --force --quiet --inline-suppr . + # build HTML documentation + - name: "htmldocs" + script: + - make htmldocs # search for TODO within source tree - name: "grep TODO" script: -- 2.25.0