| Message ID | 20200221032637.142330-2-xypron.glpk@gmx.de |
|---|---|
| State | Superseded |
| Headers | show |
| Series | doc: build HTML docs in CI | expand |
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 at 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 at 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
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) \
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 at gmx.de> --- doc/Makefile | 1 + 1 file changed, 1 insertion(+) -- 2.25.0