Merge branch '2020-02-24-ci-htmldocs'
- Update our CI loops to run 'make htmldocs' and stop on errors
diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml
index c220958..8648058 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 @@
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 d486e72..55943bb 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 @@
# 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 e6db9d6..7ab855a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -22,6 +22,7 @@
- libsdl2-dev
- python
- python-pyelftools
+ - python3-sphinx
- python3-virtualenv
- python3-pip
- swig
@@ -38,6 +39,7 @@
- libisl15
- clang-7
- srecord
+ - graphviz
install:
# Clone uboot-test-hooks
@@ -352,6 +354,10 @@
- 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 5135a96..0e0da56 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -56,6 +56,7 @@
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 e536360..4bcbd6a 100644
--- a/doc/sphinx/kerneldoc.py
+++ b/doc/sphinx/kerneldoc.py
@@ -37,7 +37,17 @@
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 @@
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 @@
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 @@
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 @@
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 @@
(" ".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')