Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Revert Python to 3.7.9 in docs-builder, downgrade a dependency #24099

Merged
merged 1 commit into from Mar 1, 2023

Conversation

qmonnet
Copy link
Member

@qmonnet qmonnet commented Mar 1, 2023

Some time ago, we updated the version of the Python interpreter in the Dockerfile for the docs-builder image. But we didn't realise that this would introduce a difference with the version in use on the Read The Docs platform. For a long period it didn't cause any issue, but the latest update of Sphinx dependencies bumped sphinxcontrib-applehelp to a version which is no longer compatible with Python 3.7. The build would run fine locally and in CI with Python 3.10, but would fail on Read The Docs where Python 3.7.9 is still in use.

We have two options: revert back to Python 3.7 in the docs-builder image, or make Read The Docs use a newer version. Updating the version on RTD sounds sensible, but there's no concrete advantage at this point, and we would have to introduce a .readthedocs.yaml file at the root of the Cilium repository, which we haven't needed so far. Conversely, there's no apparent drawback to stick to the older Python version in the docs-builder image, so we can just do that.

In addition to the Python version change, we need to regenerate the list of dependencies. Some are updated to their latest version, some seem to be slightly renamed, but note the downgrade for sphinxcontrib-applehelp. This should fix the builds on Read The Docs.

Fixes: 2b3207e ("docs: update Alpine image for cilium/docs-builder")
Fixes: #19348
Fixes: eb1338a ("docs: Update build dependencies (Sphinx add-ons etc.)")
Fixes: #24014

docs: Revert Python version in docs-builder image to 3.7.9, downgrade sphinxcontrib-applehelp, to fix builds on Read The Docs

@qmonnet qmonnet added area/documentation Impacts the documentation, including textual changes, sphinx, or other doc generation code. release-note/misc This PR makes changes that have no direct user impact. labels Mar 1, 2023
@qmonnet qmonnet requested a review from joestringer March 1, 2023 10:11
@qmonnet qmonnet force-pushed the pr/qmonnet/docs-python-version-fix branch 3 times, most recently from d103451 to 948e31b Compare March 1, 2023 15:52
@qmonnet qmonnet added the dont-merge/blocked Another PR must be merged before this one. label Mar 1, 2023
@qmonnet qmonnet marked this pull request as ready for review March 1, 2023 15:53
@qmonnet qmonnet requested review from a team as code owners March 1, 2023 15:53
@qmonnet qmonnet requested a review from tklauser March 1, 2023 15:53
Some time ago, we updated the version of the Python interpreter in the
Dockerfile for the docs-builder image. But we didn't realise that this
would introduce a difference with the version in use on the Read The
Docs platform. For a long period it didn't cause any issue, but the
latest update of Sphinx dependencies bumped sphinxcontrib-applehelp to a
version which is no longer compatible with Python 3.7. The build would
run fine locally and in CI with Python 3.10, but would fail on Read The
Docs where Python 3.7.9 is still in use.

We have two options: revert back to Python 3.7 in the docs-builder
image, or make Read The Docs use a newer version. Updating the version
on RTD sounds sensible, but there's no concrete advantage at this point,
and we would have to introduce a .readthedocs.yaml file at the root of
the Cilium repository, which we haven't needed so far. Conversely,
there's no apparent drawback to stick to the older Python version in the
docs-builder image, so we can just do that.

In addition to the Python version change, we need to regenerate the list
of dependencies. Some are updated to their latest version, some seem to
be slightly renamed, but note the downgrade for sphinxcontrib-applehelp.
This should fix the builds on Read The Docs.

We also update the docs-builder in the CI workflow, to make sure we do
not introduce another plug-in incompatible with Read The Docs's Python.

Fixes: 2b3207e ("docs: update Alpine image for cilium/docs-builder")
Fixes: eb1338a ("docs: Update build dependencies (Sphinx add-ons etc.)")
Signed-off-by: Quentin Monnet <quentin@isovalent.com>
@qmonnet qmonnet force-pushed the pr/qmonnet/docs-python-version-fix branch from 948e31b to 633edee Compare March 1, 2023 17:25
@qmonnet qmonnet removed the dont-merge/blocked Another PR must be merged before this one. label Mar 1, 2023
@qmonnet
Copy link
Member Author

qmonnet commented Mar 1, 2023

I updated the workflow with the new docs-builder image and it's passing, all good from CI side.

@joestringer joestringer merged commit 0b93dcc into master Mar 1, 2023
@joestringer joestringer deleted the pr/qmonnet/docs-python-version-fix branch March 1, 2023 18:48
@qmonnet qmonnet added the backport-pending/1.13 The backport for Cilium 1.13.x for this PR is in progress. label Jul 24, 2023
@qmonnet qmonnet added backport-pending/1.12 backport-done/1.12 The backport for Cilium 1.12.x for this PR is done. and removed backport-pending/1.12 labels Jul 25, 2023
@aanm aanm added needs-backport/1.13 This PR / issue needs backporting to the v1.13 branch backport-pending/1.13 The backport for Cilium 1.13.x for this PR is in progress. and removed backport-pending/1.13 The backport for Cilium 1.13.x for this PR is in progress. needs-backport/1.13 This PR / issue needs backporting to the v1.13 branch labels Jul 26, 2023
@qmonnet qmonnet added backport-done/1.13 The backport for Cilium 1.13.x for this PR is done. and removed backport-pending/1.13 The backport for Cilium 1.13.x for this PR is in progress. labels Jul 27, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/documentation Impacts the documentation, including textual changes, sphinx, or other doc generation code. backport-done/1.12 The backport for Cilium 1.12.x for this PR is done. backport-done/1.13 The backport for Cilium 1.13.x for this PR is done. release-note/misc This PR makes changes that have no direct user impact.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants