[PATCH 0/2] doc: build HTML docs in CI

[PATCH 0/2] doc: build HTML docs in CI

[Heinrich Schuchardt]

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

[PATCH 1/2] doc/Makefile: turn warnings into errors

[Heinrich Schuchardt]

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

[PATCH 2/2] travis: build HTML docs

[Heinrich Schuchardt]

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

[PATCH 1/2] doc/Makefile: turn warnings into errors

[Tom Rini]

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!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20200220/2ca132e1/attachment.sig>

[PATCH 1/2] doc/Makefile: turn warnings into errors

[Heinrich Schuchardt]

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

[PATCH 1/2] doc/Makefile: turn warnings into errors

[Heinrich Schuchardt]

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

[PATCH 1/2] doc/Makefile: turn warnings into errors

[Tom Rini]

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!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20200221/136d396e/attachment.sig>

[PATCH 1/2] doc/Makefile: turn warnings into errors

[Bin Meng]

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

[PATCH 2/2] travis: build HTML docs

[Bin Meng]

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>

[PATCH 2/2] travis: build HTML docs

[Bin Meng]

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