| 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 |
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.
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
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