diff options
| -rw-r--r-- | .azure-pipelines.yml | 12 | ||||
| -rw-r--r-- | .gitlab-ci.yml | 9 | ||||
| -rw-r--r-- | .travis.yml | 6 | ||||
| -rw-r--r-- | doc/Makefile | 1 | ||||
| -rw-r--r-- | doc/sphinx/kerneldoc.py | 51 |
5 files changed, 65 insertions, 14 deletions
diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index c22095830c..86480581a2 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. @@ -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: diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index d486e72042..55943bb3a2 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: @@ -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' ] diff --git a/.travis.yml b/.travis.yml index e6db9d6a72..7ab855acb2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -22,6 +22,7 @@ addons: - libsdl2-dev - python - python-pyelftools + - python3-sphinx - python3-virtualenv - python3-pip - swig @@ -38,6 +39,7 @@ addons: - libisl15 - clang-7 - srecord + - graphviz install: # Clone uboot-test-hooks @@ -352,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: 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) \ 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') |