CODEWITHSUNDEEP
python-sphinxdocutilsapple-help
Trdiaz
Trdiaz

Reputation: 33

sphinxcontrib.applehelp breaking sphinx builds with sphinx version less than 5.0

In early January 2024, all my sphinx builds failed, with this message when I did a make html:

The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

Can someone explain what caused this apparent dependency on >= 5.0? Is sphinxcontrib.applehelp part of the standard Sphinx distribution, and thus, does this situation mean Sphinx versions less than 5 are not usable?

What is the best workaround? Is there a way to build without applehelp?

Obviously one can just bump up the Sphinx version, but other items (like, in my case, the sphinx_rtd_theme) do not always work with arbitrary Sphinx versions.

I tried using this combination:

    docutils==0.16
    sphinx==5.3
    sphinx_rtd_theme==1.0.0

This builds but produces HTML sites without working full-text search, which I suspect is a sphinx_rtd_theme problem.

"Working" means a couple of critical things:

Before this new dependency on ≥ 5.0 popped up, the combinations

sphinx==4.5, sphinx_rtd_theme==1.0.0

and

sphinx==3.5.4, sphinx_rtd_theme==1.0.0, and jinja2==3.0.3

were working for me in different builds.

Upvotes: 3

Views: 834

Answers (1)

Steve Piercy
Steve Piercy

Reputation: 15075

I had the same problem with Plone 6 Documentation. Until I can upgrade to Sphinx >=5, I have these pins in place.

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

Sphinx does not do a good job of documenting what changes in these dependencies, and which versions of Sphinx are supported. So I used our GitHub Workflow history to find the last successful build, where I output all installed packages and versions. You could also use a pip freeze step to make it more legible.

Upvotes: 3

Related Questions