docs: Fix dependency conflict #14264
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Pip 20.3 introduced a new dependency resolver[[0]] which silently reinterprets our current requirements file in a different way to resolve the dependencies, which results the build being broken. On non-aarch64 systems, there are two requirements that satisfy the sphinx-rtd-theme package: * One provided by our own theme repository[[1]] which has nice consistent theming for the website, and * One provided by the upstream sphinx-rtd-theme package. Prior to pip 20.3, the default resolver was able to resolve this conflict to favour our custom theme, which is the one we intend to use in most cases. Unfortunately, with the new resolver, this conflict is resolved the other way. As far as I can tell, there is no "strict" mode to prescribe that pip should resolve conflicts first and fail out if the requirements are ambiguous. Instead, pip silently resolves this conflict and we do not find out that there was ambiguity until later in the process. In addition, on readthedocs.org, new versions of pip are automatically pulled upon each new docs build, which meant that from one day to the next, a previously successful build began to consistently fail with weird errors that imply a problem with the dependency but don't explain why the problem was introduced without changes to code in our build system: Theme error: no theme named 'sphinx_rtd_theme_cilium' found (missing theme.conf?) make[1]: *** [Makefile:48: html] Error 2 make: *** [Makefile:552: test-docs] Error 2 Fix the issue by disambiguating the theme dependency. [0]: http://pyfound.blogspot.com/2020/11/pip-20-3-new-resolver.html [1]: https://github.com/cilium/sphinx_rtd_theme Fixes: cilium#14252 Signed-off-by: Joe Stringer <joe@cilium.io>
maintainer-s-little-helper
bot
added
the
dont-merge/needs-release-note-label
joestringer
added
the
release-note/misc
maintainer-s-little-helper
bot
removed
the
dont-merge/needs-release-note-label
qmonnet
approved these changes
Dec 4, 2020
qmonnet
added
the
ready-to-merge
joestringer
moved this from Needs backport from master
to Backport done to v1.9
in 1.9.2
joestringer
moved this from Needs backport from master
to Backport done to v1.8
in 1.8.7
joestringer
moved this from Needs backport from master
to Backport done to v1.7
in 1.7.13
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pip 20.3 introduced a new dependency resolver[0] which silently
reinterprets our current requirements file in a different way to
resolve the dependencies, which results the build being broken.
On non-aarch64 systems, there are two requirements that satisfy
the sphinx-rtd-theme package:
theming for the website, and
Prior to pip 20.3, the default resolver was able to resolve this
conflict to favour our custom theme, which is the one we intend to use
in most cases. Unfortunately, with the new resolver, this conflict is
resolved the other way. As far as I can tell, there is no "strict" mode
to prescribe that pip should resolve conflicts first and fail out if the
requirements are ambiguous. Instead, pip silently resolves this conflict
and we do not find out that there was ambiguity until later in the
process.
In addition, on readthedocs.org, new versions of pip are automatically
pulled upon each new docs build, which meant that from one day to the
next, a previously successful build began to consistently fail with
weird errors that imply a problem with the dependency but don't explain
why the problem was introduced without changes to code in our build
system:
Fix the issue by disambiguating the theme dependency.
Fixes: #14252