- Sponsor
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Description
Describe the bug
I'm having trouble fully understanding why this is happening, but I'll try to describe things as best I can.
The issue we're noticing is that if you install Sphinx < 5 in a fresh environment, your build will fail with the exception:
sphinx.errors.VersionRequirementError: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
It seems the releases of the sphinxcontrib-*help
packages a few days ago are maybe avoiding proper dependency resolution now. I noticed with pip and poetry that install Sphinx 4.5.0 still grabbed the latest versions of these packages.
It seems this might all be related to commits similar to: sphinx-doc/sphinxcontrib-applehelp@ccc77c8
4 days prior to this, the build was successful, and Poetry installed the following dependencies while install Sphinx 4.5:
sphinxcontrib-applehelp-1.0.4
sphinxcontrib-devhelp-1.0.2
sphinxcontrib-htmlhelp-2.0.1
sphinxcontrib-qthelp-1.0.3
sphinxcontrib-serializinghtml-1.1.5
This is also maybe similar to problems in the past with docutils, Jinja, and other unpinned dependencies. New releases of these packages, and unpinned dependencies at Sphinx, caused abrupt upgrades to dependencies.
For anyone hitting this issue, you can upgrade Sphinx or pin the dependencies that were recently updated:
[tool.poetry.dependencies]
...
sphinxcontrib-applehelp = "1.0.4"
sphinxcontrib-devhelp = "1.0.2"
sphinxcontrib-htmlhelp = "2.0.1"
sphinxcontrib-qthelp = "1.0.3"
sphinxcontrib-serializinghtml = "1.1.5"
How to Reproduce
Here is a build on RTD showing the package installation, environment, and the build exception. Most importantly, note the Sphinx version is 4.5.0 and the sphinxcontrib-*help
packages are all the latest releases.
https://readthedocs.org/projects/test-builds/builds/23151025/
Environment Information
https://readthedocs.org/projects/test-builds/builds/23151025/
Sphinx extensions
No response
Additional context
No response
Activity
AA-Turner commentedon Jan 17, 2024
Sphinx only supports the latest version (i.e. currently 7.2.6; version 5 is unsupported). Sadly, Python's dependency system doesn't allow us to specify that the new versions of the sphinxcontrib packages require Sphinx 5 or newer without causing issues for others.
c.f.:
Sphinx
andsphinxcontrib-*
#11567A
agjohnson commentedon Jan 17, 2024
Yeah, I understand maintainers support only the latest release series, but I suppose I'm also not suggesting changing previous releases. This is a bug introduced with the recent help packages, and can be addressed there. I worry that this is a user hostile change, as the deprecation happens without warning.
AA-Turner commentedon Jan 18, 2024
I'm open to suggestions, but what seems natural (adding a requirement of
Sphinx>=5
) causes problems for others, I'm told (#11567). I don't mind what the end outcome is, I simply want to minimise complaints!A
agjohnson commentedon Jan 18, 2024
Hah yeah, understand that completely. I wish I could suggest a better fix, but these changes are getting pretty deep into the arcane arts of Python packaging. I don't know what configuration would still allow Poetry/pip/etc to resolve the same dependencies as Bazel (outside explicit package pinning of course).
For now, we see projects hitting this on RTD, but our build failure rate is not remarkably higher yet either. I don't have recent figures, but projects pinning Sphinx<=4 represent a shrinking but not trivial number of projects.
Sphinx
andsphinxcontrib-*
#11567Rapptz commentedon Jan 26, 2024
This issue happens because Sphinx itself doesn't pin dependencies as seen here:
sphinx/pyproject.toml
Lines 59 to 64 in fa29004
To prevent this from happening in the future those dependencies should be pinned to a specific version. Likewise, the
sphixncontrib-
packages should probably either do a major version bump due to changed requirements (bumping it is technically a breaking change, since its API surface is loading the extension now breaks) though even that wouldn't have saved this error since Sphinx doesn't pin the dependencies.AlexanderJuestel commentedon Jan 28, 2024
Running into the same issue here: https://readthedocs.org/projects/pyhd/builds/23253592/
wanglinsong commentedon Jan 29, 2024
Any solution to this error?
[20240129 004530] The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.
fozog commentedon Jan 30, 2024
Changing requirements.txt solved the issue with me:
s/sphinx==4.5.0/sphinx==5.0.2
wanglinsong commentedon Jan 30, 2024
Thanks. I just did that.
requirements: fix for sphinxcontrib.applehelp
Use newer Sphinx (satisfy `sphinxcontrib-applehelp`)