Skip to content

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

@agjohnson

Description

@agjohnson
Contributor

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

AA-Turner commented on Jan 17, 2024

@AA-Turner
Member

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

A

agjohnson

agjohnson commented on Jan 17, 2024

@agjohnson
ContributorAuthor

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

AA-Turner commented on Jan 18, 2024

@AA-Turner
Member

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

agjohnson commented on Jan 18, 2024

@agjohnson
ContributorAuthor

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

Rapptz commented on Jan 26, 2024

@Rapptz
Contributor

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

AlexanderJuestel commented on Jan 28, 2024

@AlexanderJuestel
wanglinsong

wanglinsong commented on Jan 29, 2024

@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

fozog commented on Jan 30, 2024

@fozog

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

wanglinsong

wanglinsong commented on Jan 30, 2024

@wanglinsong

Thanks. I just did that.

locked as resolved and limited conversation to collaborators on Mar 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @agjohnson@Rapptz@AA-Turner@fozog@wanglinsong

        Issue actions

          sphinx.errors.VersionRequirementError: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0 · Issue #11890 · sphinx-doc/sphinx