[yocto-autobuilder-helper,4/4] Revert "scripts: run-docs-build: do not turn sphinx warnings into errors"

Message ID 20220315163115.2186540-4-foss+yocto@0leil.net
State New
Headers show
Series [yocto-autobuilder-helper,1/4] scripts: run-docs-build: simplify patching logic | expand

Commit Message

Quentin Schulz March 15, 2022, 4:31 p.m. UTC
From: Quentin Schulz <quentin.schulz@theobroma-systems.com>

The patch was meant as a quick temporary work-around to have the docs
built and published.

Now that releases where -W flag is set (turning warnings into errors)
are appropriately patched to make those warnings disappear (on Sphinx
v3.2.1 which is the one used on the builder), this patch can be reverted
so that next time a warning appears the doc building will fail but will
not destroy the doc website (because of commit
6a4e6ef18d1415c719be51c773d7c57cae5549cf "scripts: run-docs-build: make
the script fail hard ASAP when there's an error", since rsync will not
be run if any error happens before).

This reverts commit 931d409b255a85f2217ca093d8391a678ce00ddb.

Cc: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
---
 scripts/run-docs-build | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

Comments

Michael Opdenacker June 22, 2022, 12:50 p.m. UTC | #1
Hi Quentin

On 3/15/22 17:31, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@theobroma-systems.com>
>
> The patch was meant as a quick temporary work-around to have the docs
> built and published.
>
> Now that releases where -W flag is set (turning warnings into errors)
> are appropriately patched to make those warnings disappear (on Sphinx
> v3.2.1 which is the one used on the builder), this patch can be reverted
> so that next time a warning appears the doc building will fail but will
> not destroy the doc website (because of commit
> 6a4e6ef18d1415c719be51c773d7c57cae5549cf "scripts: run-docs-build: make
> the script fail hard ASAP when there's an error", since rsync will not
> be run if any error happens before).
>
> This reverts commit 931d409b255a85f2217ca093d8391a678ce00ddb.
>
> Cc: Quentin Schulz <foss+yocto@0leil.net>
> Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> ---
>   scripts/run-docs-build | 16 ++++++++--------
>   1 file changed, 8 insertions(+), 8 deletions(-)
>
> diff --git a/scripts/run-docs-build b/scripts/run-docs-build
> index 73cba3f..b9b331b 100755
> --- a/scripts/run-docs-build
> +++ b/scripts/run-docs-build
> @@ -33,14 +33,14 @@ cd $bbdocs
>   echo Building bitbake master branch
>   git checkout master
>   make clean
> -SPHINXOPTS="-j auto" make publish
> +make publish
>   mkdir $outputdir/bitbake
>   cp -r ./_build/final/* $outputdir/bitbake

We're trying to build the docs with Sphinx 5.0.0 on a special branch, 
and we're getting warnings causing the builds to fail: 
https://autobuilder.yoctoproject.org/typhoon/#/builders/114/builds/487/steps/5/logs/stdio

If this patch hadn't been reverted, we would probably be fine.

What should we do now? Patch docs for all past Sphinx based releases? If 
we tolerated warnings, we would have to do this less often when we want 
to upgrade Sphinx.

In my opinion, another more trouble-free solution would be not to 
regenerate docs for past releases, but instead only for the latest 
commits in the branches we currently support.

What do you think?
Cheers
Michael.
Richard Purdie June 22, 2022, 1:02 p.m. UTC | #2
On Wed, 2022-06-22 at 14:50 +0200, Michael Opdenacker wrote:
> Hi Quentin
> 
> On 3/15/22 17:31, Quentin Schulz wrote:
> > From: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> > 
> > The patch was meant as a quick temporary work-around to have the docs
> > built and published.
> > 
> > Now that releases where -W flag is set (turning warnings into errors)
> > are appropriately patched to make those warnings disappear (on Sphinx
> > v3.2.1 which is the one used on the builder), this patch can be reverted
> > so that next time a warning appears the doc building will fail but will
> > not destroy the doc website (because of commit
> > 6a4e6ef18d1415c719be51c773d7c57cae5549cf "scripts: run-docs-build: make
> > the script fail hard ASAP when there's an error", since rsync will not
> > be run if any error happens before).
> > 
> > This reverts commit 931d409b255a85f2217ca093d8391a678ce00ddb.
> > 
> > Cc: Quentin Schulz <foss+yocto@0leil.net>
> > Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>
> > ---
> >   scripts/run-docs-build | 16 ++++++++--------
> >   1 file changed, 8 insertions(+), 8 deletions(-)
> > 
> > diff --git a/scripts/run-docs-build b/scripts/run-docs-build
> > index 73cba3f..b9b331b 100755
> > --- a/scripts/run-docs-build
> > +++ b/scripts/run-docs-build
> > @@ -33,14 +33,14 @@ cd $bbdocs
> >   echo Building bitbake master branch
> >   git checkout master
> >   make clean
> > -SPHINXOPTS="-j auto" make publish
> > +make publish
> >   mkdir $outputdir/bitbake
> >   cp -r ./_build/final/* $outputdir/bitbake
> 
> We're trying to build the docs with Sphinx 5.0.0 on a special branch, 
> and we're getting warnings causing the builds to fail: 
> https://autobuilder.yoctoproject.org/typhoon/#/builders/114/builds/487/steps/5/logs/stdio
> 
> If this patch hadn't been reverted, we would probably be fine.
> 
> What should we do now? Patch docs for all past Sphinx based releases? If 
> we tolerated warnings, we would have to do this less often when we want 
> to upgrade Sphinx.
> 
> In my opinion, another more trouble-free solution would be not to 
> regenerate docs for past releases, but instead only for the latest 
> commits in the branches we currently support.
> 
> What do you think?

We use the ability to regenerate previous releases to update the
switcher lists and potentially other style related changes in future
which keeps the docs looking consistent. We may have to disable the
errors on warnings :(

Cheers,

Richard

Patch

diff --git a/scripts/run-docs-build b/scripts/run-docs-build
index 73cba3f..b9b331b 100755
--- a/scripts/run-docs-build
+++ b/scripts/run-docs-build
@@ -33,14 +33,14 @@  cd $bbdocs
 echo Building bitbake master branch
 git checkout master
 make clean
-SPHINXOPTS="-j auto" make publish
+make publish
 mkdir $outputdir/bitbake
 cp -r ./_build/final/* $outputdir/bitbake
 
 git checkout master-next
 echo Building bitbake master-next branch
 make clean
-SPHINXOPTS="-j auto" make publish
+make publish
 mkdir $outputdir/bitbake/next
 cp -r ./_build/final/* $outputdir/bitbake/next
 
@@ -55,7 +55,7 @@  for branch in 1.46 1.48 1.50 1.52; do
     git checkout $branch
     git checkout master releases.rst
     make clean
-    SPHINXOPTS="-j auto" make publish
+    make publish
     mkdir $outputdir/bitbake/$branch
     cp -r ./_build/final/* $outputdir/bitbake/$branch
     git reset --hard
@@ -70,21 +70,21 @@  cd $ypdocs
 echo Building master branch
 git checkout master
 make clean
-SPHINXOPTS="-j auto" make publish
+make publish
 cp -r ./_build/final/* $outputdir
 
 cd $ypdocs
 echo Building transition branch
 git checkout transition
 make clean
-SPHINXOPTS="-j auto" make publish
+make publish
 cp -r ./_build/final/* $outputdir/
 
 cd $ypdocs
 echo Building master-next branch
 git checkout master-next
 make clean
-SPHINXOPTS="-j auto" make publish
+make publish
 mkdir $outputdir/next
 cp -r ./_build/final/* $outputdir/next
 
@@ -96,7 +96,7 @@  for branch in dunfell gatesgarth hardknott honister; do
     git checkout $branch
     git checkout master releases.rst
     make clean
-    SPHINXOPTS="-j auto" make publish
+    make publish
     mkdir $outputdir/$branch
     cp -r ./_build/final/* $outputdir/$branch
     git reset --hard
@@ -117,7 +117,7 @@  for tag in $(git tag --list 'yocto-*'); do
         fi
         git checkout master releases.rst
         make clean
-        SPHINXOPTS="-j auto" make publish
+        make publish
         version=$(echo $tag | cut -c7-)
         mkdir $outputdir/$version
         cp -r ./_build/final/* $outputdir/$version