[PATCH 0/2] doc: build HTML docs in CI
We are on the move to a restructured text based documentation for U-Boot. Build target htmldocs is used to transform the restructured text into HTML. We should avoid syntax errors in the restructured text documents that may lead to incorrect HTML.
This patch series turns the 'make htmldocs' warnings into errors and adds build steps for 'make htmldocs' to Travis CI scripts.
I am still working on Gitlab. At least imagemagick (/usr/bin/convert) is missing in our Docker image.
Heinrich Schuchardt (2): doc/Makefile: turn warnings into errors travis: build HTML docs
.travis.yml | 5 +++++ doc/Makefile | 1 + 2 files changed, 6 insertions(+)
-- 2.25.0
Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI or Gitlab CI.
So let us turn all build warnings into errors.
We cannot add --keep-going as Gitlab does not use sphinx-build version 1.8 or later yet.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de --- 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) \ -- 2.25.0
On Fri, Feb 21, 2020 at 04:26:36AM +0100, Heinrich Schuchardt wrote:
Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI or Gitlab CI.
So let us turn all build warnings into errors.
We cannot add --keep-going as Gitlab does not use sphinx-build version 1.8 or later yet.
Why can't we upgrade sphinx-build so that we then run these builds also in Gitlab / Azure? Thanks!
On 2/21/20 5:06 AM, Tom Rini wrote:
On Fri, Feb 21, 2020 at 04:26:36AM +0100, Heinrich Schuchardt wrote:
Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI or Gitlab CI.
So let us turn all build warnings into errors.
We cannot add --keep-going as Gitlab does not use sphinx-build version 1.8 or later yet.
Why can't we upgrade sphinx-build so that we then run these builds also in Gitlab / Azure? Thanks!
This is what --keep-going does:
With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1.
So for the purpose of checking if there is *any* error in the documentation this flag does not make a difference.
If we put the --keep-going flag into our Makefile, we require everybody in the U-Boot community to upgrade his Sphinx installation if he wants to run 'make htmldocs'. Is this what we want?
Our Dockerfile is based on ubuntu:bionic-20200112. You could move to ubuntu:eoan-20200114 to get Sphinx 1.8.5.
Best regards
Heinrich
On 2/21/20 5:31 AM, Heinrich Schuchardt wrote:
On 2/21/20 5:06 AM, Tom Rini wrote:
On Fri, Feb 21, 2020 at 04:26:36AM +0100, Heinrich Schuchardt wrote:
Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI or Gitlab CI.
So let us turn all build warnings into errors.
We cannot add --keep-going as Gitlab does not use sphinx-build version 1.8 or later yet.
Why can't we upgrade sphinx-build so that we then run these builds also in Gitlab / Azure? Thanks!
Maybe this was unclear to you: My choice was not to use --keep-going because I want run the test in the current Gitlab Docker image. With the patch as it is we can run on Gitlab.
But there is another package (imagemagick) missing in the Dockerimage. I am currently testing if this is the only missing package. I will submit the .gitlab-ci.yml patch thereafter.
This is what --keep-going does:
With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1.
So for the purpose of checking if there is *any* error in the documentation this flag does not make a difference.
If we put the --keep-going flag into our Makefile, we require everybody in the U-Boot community to upgrade his Sphinx installation if he wants to run 'make htmldocs'. Is this what we want?
Our Dockerfile is based on ubuntu:bionic-20200112. You could move to ubuntu:eoan-20200114 to get Sphinx 1.8.5.
Best regards
Heinrich
On Fri, Feb 21, 2020 at 05:43:40AM +0100, Heinrich Schuchardt wrote:
On 2/21/20 5:31 AM, Heinrich Schuchardt wrote:
On 2/21/20 5:06 AM, Tom Rini wrote:
On Fri, Feb 21, 2020 at 04:26:36AM +0100, Heinrich Schuchardt wrote:
Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI or Gitlab CI.
So let us turn all build warnings into errors.
We cannot add --keep-going as Gitlab does not use sphinx-build version 1.8 or later yet.
Why can't we upgrade sphinx-build so that we then run these builds also in Gitlab / Azure? Thanks!
Maybe this was unclear to you: My choice was not to use --keep-going because I want run the test in the current Gitlab Docker image. With the patch as it is we can run on Gitlab.
Ah, yes, OK. The commit message isn't clear. We should just drop that line about --keep-going. Thanks!
On Fri, Feb 21, 2020 at 11:27 AM Heinrich Schuchardt xypron.glpk@gmx.de wrote:
Several patches delivered incorrect restructured text as documentation. We should be able to discover this in Travis CI or Gitlab CI.
should mention Azure as well.
So let us turn all build warnings into errors.
We cannot add --keep-going as Gitlab does not use sphinx-build version 1.8 or later yet.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de
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) \--
Regards, Bin
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 --- .travis.yml | 5 +++++ 1 file changed, 5 insertions(+)
diff --git a/.travis.yml b/.travis.yml index e6db9d6a72..a5918dd5d9 100644 --- a/.travis.yml +++ b/.travis.yml @@ -38,6 +38,7 @@ addons: - libisl15 - clang-7 - srecord + - graphviz
install: # Clone uboot-test-hooks @@ -360,6 +361,10 @@ matrix: - name: "grep FIXME HACK" script: - grep -r FIXME . + # build HTML documentation + - name: "htmldocs" + script: + - make htmldocs # search for HACK within source tree and ignore HACKKIT board script: - grep -r HACK . | grep -v HACKKIT -- 2.25.0
On Fri, Feb 21, 2020 at 11:27 AM Heinrich Schuchardt xypron.glpk@gmx.de wrote:
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
.travis.yml | 5 +++++ 1 file changed, 5 insertions(+)
Reviewed-by: Bin Meng bmeng.cn@gmail.com
On Fri, Feb 21, 2020 at 11:27 AM Heinrich Schuchardt xypron.glpk@gmx.de wrote:
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
.travis.yml | 5 +++++ 1 file changed, 5 insertions(+)
diff --git a/.travis.yml b/.travis.yml index e6db9d6a72..a5918dd5d9 100644 --- a/.travis.yml +++ b/.travis.yml @@ -38,6 +38,7 @@ addons: - libisl15 - clang-7 - srecord
- graphviz
install: # Clone uboot-test-hooks @@ -360,6 +361,10 @@ matrix: - name: "grep FIXME HACK" script: - grep -r FIXME .
- # build HTML documentation
- name: "htmldocs"
script:- make htmldocs
Could you insert this after cppcheck, to align with what you did in gitlab and azure?
# search for HACK within source tree and ignore HACKKIT board script: - grep -r HACK . | grep -v HACKKIT--
Regards, Bin
participants (3)
-
Bin Meng -
Heinrich Schuchardt -
Tom Rini