sphinx.errors.VersionRequirementError: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0

[agjohnson]

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

[AA-Turner]

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

• Circular dependencies between Sphinx and sphinxcontrib-* #11567
• Remove Sphinx as a required dependency sphinxcontrib-applehelp#15

A

[agjohnson]

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]

can be addressed there

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]

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.

[Rapptz]

This issue happens because Sphinx itself doesn't pin dependencies as seen here:

sphinx/pyproject.toml

Lines 59 to 64 in fa29004

	"sphinxcontrib-applehelp",
	"sphinxcontrib-devhelp",
	"sphinxcontrib-jsmath",
	"sphinxcontrib-htmlhelp>=2.0.0",
	"sphinxcontrib-serializinghtml>=1.1.9",
	"sphinxcontrib-qthelp",

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]

Running into the same issue here: https://readthedocs.org/projects/pyhd/builds/23253592/

[wanglinsong]

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]

Changing requirements.txt solved the issue with me:
s/sphinx==4.5.0/sphinx==5.0.2

[wanglinsong]

Thanks. I just did that.