From 15ae50002688b25075b9a7653e8b9ce4c76bc384 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Mon, 24 Feb 2020 11:04:29 -0500 Subject: [PATCH 1/7] Azure / GitLab: Update Docker image Bring in a newer Docker image to build on that has everything required for running 'make htmldocs'. Signed-off-by: Tom Rini --- .azure-pipelines.yml | 2 +- .gitlab-ci.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index c22095830c..c2f7f0f133 100644 --- a/.azure-pipelines.yml +++ b/.azure-pipelines.yml @@ -1,7 +1,7 @@ variables: windows_vm: vs2017-win2016 ubuntu_vm: ubuntu-18.04 - ci_runner_image: trini/u-boot-gitlab-ci-runner:bionic-20200112-07Feb2020 + ci_runner_image: trini/u-boot-gitlab-ci-runner:bionic-20200112-21Feb2020 # Add '-u 0' options for Azure pipelines, otherwise we get "permission # denied" error when it tries to "useradd -m -u 1001 vsts_azpcontainer", # since our $(ci_runner_image) user is not root. diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index d486e72042..a525ea2ce0 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -2,7 +2,7 @@ # Grab our configured image. The source for this is found at: # https://gitlab.denx.de/u-boot/gitlab-ci-runner -image: trini/u-boot-gitlab-ci-runner:bionic-20200112-07Feb2020 +image: trini/u-boot-gitlab-ci-runner:bionic-20200112-21Feb2020 # We run some tests in different order, to catch some failures quicker. stages: From d94a3d17079dbf6278628686d69dc30c8e67b5b7 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 21 Feb 2020 18:23:59 +0100 Subject: [PATCH 2/7] doc: update doc/sphinx/kerneldoc.py 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 --- 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') From f36f15b64b65f949ea0afe781fefe93c2e803ebd Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Mon, 24 Feb 2020 15:10:36 -0500 Subject: [PATCH 3/7] travis: Add python3-sphinx to the package list In order to build htmldocs we need sphinx-build which comes from python3-sphinx. Signed-off-by: Tom Rini --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index e6db9d6a72..11f9757d88 100644 --- a/.travis.yml +++ b/.travis.yml @@ -22,6 +22,7 @@ addons: - libsdl2-dev - python - python-pyelftools + - python3-sphinx - python3-virtualenv - python3-pip - swig From bb9a76ea67fe9b85961b50d9f95b772d6859edaa Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 21 Feb 2020 18:24:00 +0100 Subject: [PATCH 4/7] travis: build HTML docs 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 Reviewed-by: Bin Meng --- .travis.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.travis.yml b/.travis.yml index 11f9757d88..7ab855acb2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -39,6 +39,7 @@ addons: - libisl15 - clang-7 - srecord + - graphviz install: # Clone uboot-test-hooks @@ -353,6 +354,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: From 3eb7b78b42373a260eb6d9996840da36a256f46e Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 21 Feb 2020 18:24:01 +0100 Subject: [PATCH 5/7] gitlab: build HTML documentation Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Gitlab CI. Provide a build step for 'make htmldocs'. Signed-off-by: Heinrich Schuchardt Reviewed-by: Bin Meng --- .gitlab-ci.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index a525ea2ce0..55943bb3a2 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -122,6 +122,13 @@ grep TODO/FIXME/HACK: # search for HACK within source tree and ignore HACKKIT board - grep -r HACK . | grep -v HACKKIT +# build HTML documentation +htmldocs: + tags: [ 'all' ] + stage: testsuites + script: + - make htmldocs + # some statistics about the code base sloccount: tags: [ 'all' ] From 4eb0fc996c6f188221c278560052d4f58f1f6968 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 21 Feb 2020 18:24:02 +0100 Subject: [PATCH 6/7] azure: build HTML documentation Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Azure CI. Provide a build step for 'make htmldocs'. Signed-off-by: Heinrich Schuchardt Reviewed-by: Bin Meng --- .azure-pipelines.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index c2f7f0f133..86480581a2 100644 --- a/.azure-pipelines.yml +++ b/.azure-pipelines.yml @@ -54,6 +54,16 @@ jobs: steps: - script: cppcheck --force --quiet --inline-suppr . + - job: htmldocs + displayName: 'Build HTML documentation' + pool: + vmImage: $(ubuntu_vm) + container: + image: $(ci_runner_image) + options: $(container_option) + steps: + - script: make htmldocs + - job: todo displayName: 'Search for TODO within source tree' pool: From f3957b69fd1d691c0129d3dd3283169056d3c928 Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Fri, 21 Feb 2020 18:24:03 +0100 Subject: [PATCH 7/7] doc/Makefile: turn warnings into errors Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI, Gitlab CI, or Azure CI. So let us turn all build warnings into errors. Signed-off-by: Heinrich Schuchardt Reviewed-by: Bin Meng --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/Makefile b/doc/Makefile index 5135a96e88..0e0da5666f 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -56,6 +56,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(SPHINXBUILD) \ + -W \ -b $2 \ -c $(abspath $(srctree)/$(src)) \ -d $(abspath $(BUILDDIR)/.doctrees/$3) \