All jobs

Fix "The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0"

Yes. An agent rebuilds the docs environment as your host installs it, then pins the five sphinxcontrib packages or raises Sphinx, with a build to show for it.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

This error appears in documentation builds that nobody changed. A project pins an old Sphinx, such as Sphinx==4.2.0, and installs it into a fresh environment on every build. Sphinx 4 depends on a family of small packages (sphinxcontrib-applehelp, -devhelp, -htmlhelp, -qthelp, -serializinghtml) with no upper limit on their versions, and current releases of those packages refuse to load under anything older than Sphinx 5. The installer resolves happily, and the failure arrives when Sphinx starts and reads the first of them: Sphinx version error: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

wechatpy/wechatpy is a clear case. Its docs/requirements.txt is two lines, Sphinx==4.2.0 and furo. Its .readthedocs.yml builds on Python 3.9, installs that file, then installs the package itself with pip, because docs/conf.py runs import wechatpy to read the version. The repository's CI workflow runs the tests and never builds the docs, so the only place this breaks is the documentation host. The agent starts by reproducing that exact install in its sandbox: a Python 3.9 environment, the two requirement lines, and sphinx-build -b html.

Reproducing first matters because the title error is not the only one in the queue. In a fresh environment today, Sphinx 4.2.0 can fail earlier with ModuleNotFoundError: No module named 'pkg_resources', raised from sphinx/registry.py: that Sphinx imports pkg_resources, which recent setuptools releases no longer ship. With an older setuptools present, the build reaches the applehelp message. Pin that one package and the same message names sphinxcontrib.devhelp, then htmlhelp, then serializinghtml. A person fixing this by hand meets the errors one build at a time; the agent walks the chain in one sitting and records each step.

There are two ways out and the agent tries both. The conservative one keeps Sphinx==4.2.0 and adds pins for all five packages at their last releases that accept Sphinx 4, plus a setuptools bound so pkg_resources exists. The other raises Sphinx to the newest release the configured Python supports and lets the theme follow. For each, it builds the real docs/ tree and compares the result with the settings conf.py relies on: here html_theme = "furo", language = "zh_CN", and the sphinx.ext.autodoc, sphinx.ext.todo and sphinx.ext.viewcode extensions. It then proposes the upgrade if that build is clean, falls back to the pins if it is not, and says which it chose and why.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "The documentation build fails with \"Sphinx version error: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.\" Find how the docs are built: the Read the Docs config (.readthedocs.yml or .readthedocs.yaml) if there is one, the docs requirements file, docs/conf.py, any Makefile, tox or CI job that runs sphinx-build. Recreate that environment exactly: the same Python version, the same requirement files installed with pip into a fresh virtual environment, the package itself installed if the config does that. Run the same build command and record every error in the order it appears, fixing only enough to see the next one, until the build completes. Then prepare two candidate fixes in separate fresh environments. Candidate A keeps the pinned Sphinx version and adds exact pins for sphinxcontrib-applehelp, sphinxcontrib-devhelp, sphinxcontrib-htmlhelp, sphinxcontrib-qthelp and sphinxcontrib-serializinghtml at the newest versions that work with it, plus any other pin the old Sphinx needs on a fresh install (for example a setuptools bound if it imports pkg_resources). Candidate B raises Sphinx to the newest version that supports the configured Python, updates the theme and extensions to match, and changes conf.py only where the new version requires it. Build the full docs under both with warnings shown, and compare: warnings, missing pages, theme rendering of the index page. Choose B if it builds with no new warnings, otherwise A, and explain the choice. Do not change the documentation content. Open a pull request with the requirements change, the ordered list of errors you met, and the build output for both candidates.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that changes the docs requirements file and, only if the upgrade path needs it, a line or two of conf.py. For a two-line file like the one above, candidate A keeps both lines and adds five exact sphinxcontrib-* pins and a setuptools bound. Candidate B is a higher Sphinx pin and whatever theme version resolves with it. The description shows both, so the reviewer can switch to the other without a second run.

The description also holds the ordered error list, which is the part a maintainer will reuse. It records which package each message named and what cleared it, so the next person to see needs at least Sphinx v5.0 for a different extension knows it is the same problem and that there are more behind it. The build logs for both candidates are attached to the session, warnings included.

What a reviewer should check before merging is the rendered site, not only the exit code. A major Sphinx upgrade can change theme markup, search behaviour for non-English languages and autodoc output. The agent builds the HTML and reports differences it can see in the files, and a preview build, where your documentation host offers one for pull requests, is where a person confirms the pages look right.

Run it on every Monday morning

Unpinned documentation dependencies drift without a commit, so the useful check is on a clock. Add an automation to the Project with a schedule trigger, a cron of 0 6 * * 1 and your timezone, and a prompt that rebuilds the docs environment from scratch and opens a pull request only when the build fails or warns. Most weeks the run reports a clean build and changes nothing.

Mark the automation read only if you want a report without a branch: its runs can read the repository and comment but cannot push. Leave it writable if you want the fix prepared. In both cases set max runs per hour to 1, since a weekly job has no reason to run twice.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

The failure exists only in a fresh install. A maintainer's own virtual environment was resolved months ago and still holds the old sphinxcontrib releases, so make html works on their machine while the hosted build is red. The agent's sandbox starts empty every time, which is the same condition the documentation host builds under, and it installs the configured Python version instead of whatever a laptop happens to have.

Trying both fixes means two environments, two full builds and a comparison, which is the step that gets skipped when the goal is to turn a badge green. Here both builds run in one session with their logs kept, so the pull request can say that the upgrade was attempted and what it produced, and the choice between pinning and upgrading is made on output.

Frequently asked questions

Which versions should I pin to keep Sphinx 4?

Pin all five: sphinxcontrib-applehelp==1.0.4, sphinxcontrib-devhelp==1.0.2, sphinxcontrib-htmlhelp==2.0.1, sphinxcontrib-qthelp==1.0.3 and sphinxcontrib-serializinghtml==1.1.5. Pinning only applehelp moves the error to the next package. The agent confirms the set against your Sphinx version by building, since the right numbers depend on it.

Why did this start failing when I changed nothing?

Your Sphinx pin did not move, but its dependencies were never pinned. Each build installs the newest sphinxcontrib-* releases, and those now require Sphinx 5 or later when they load. The requirement is checked at run time and is not declared to pip, so the install succeeds and the build fails.

Is upgrading Sphinx the better fix?

Usually, because pins on an unmaintained Sphinx collect more workarounds over time, such as the pkg_resources import. It is a larger change, though: themes and extensions must support the new version. That is why the run builds your docs under both and reports the difference before choosing.

Does this work for docs hosted somewhere other than Read the Docs?

Yes. The agent reads whatever defines the build, including a CI job, a tox environment or a Makefile, and recreates that. Read the Docs is simply the most common place the error is first seen, because it installs from scratch on every build.

More Sphinx jobs

More jobs like this: Upgrade dependencies weekly

Keep reading