From: Quentin Schulz <quentin.schulz@...>

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@...>
Signed-off-by: Quentin Schulz <quentin.schulz@...>
---
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

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

Hi Quentin

On 3/15/22 17:31, Quentin Schulz wrote:

From: Quentin Schulz <quentin.schulz@...>

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@...>
Signed-off-by: Quentin Schulz <quentin.schulz@...>
---
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.

--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

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

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@...>
Signed-off-by: Quentin Schulz <quentin.schulz@...>
---
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

Hello Quentin,

On 6/22/22 15:02, Richard Purdie wrote:

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

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@...>
Signed-off-by: Quentin Schulz <quentin.schulz@...>
---
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 :(

Richard and I eventually did that: disabling the errors on warnings, so that we can make progress on the Sphinx updates and the generation of epub and pdf formats.

This won´t prevent us from discussing this further at the right time.

Cheers
Michael.

--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com