sphinxcontrib.applehelp致Sphinx 5.0以下版本构建失败的技术问询

问题1：关于sphinxcontrib.applehelp的版本依赖问题 #

• 突然要求≥Sphinx 5.0的原因：该扩展的新版本更新了依赖约束——Sphinx 5.0引入了扩展需要的新API或特性，因此新版本不再兼容低版本Sphinx。
• 是否属于Sphinx标准组件：sphinxcontrib.applehelp是第三方扩展，不属于Sphinx核心发行包，但很多Sphinx项目会默认配置这类常用扩展。
• Sphinx 5.0以下是否彻底无法使用：不是。你可以锁定该扩展的旧版本（比如sphinxcontrib-applehelp==1.0.4），旧版本适配Sphinx 5.0以下版本，能正常配合使用。

问题2：最佳解决方案及是否可移除applehelp依赖 #

• 最佳方案分两种：
  • 方案一：升级Sphinx到5.0及以上版本，同时适配相关依赖（比如升级主题版本），长期来看更利于后续维护。
  • 方案二：锁定sphinxcontrib.applehelp的旧版本，继续使用低版本Sphinx，适合需要保持原有环境稳定的场景。
• 可以不依赖applehelp扩展：applehelp仅用于生成苹果系统专属的帮助文档格式，如果你只需要构建HTML文档，直接在项目的conf.py文件中，把extensions列表里的sphinxcontrib.applehelp移除即可，完全不影响HTML构建流程。

问题3：修复Sphinx 5.3+sphinx_rtd_theme 1.0.0的搜索失效问题 #

搜索失效是因为sphinx_rtd_theme==1.0.0和Sphinx 5.x版本存在兼容问题，该版本主题未适配高版本Sphinx的搜索机制。针对你的核心需求（RST列表正常生成、搜索功能可用），有两个可行方案：

方案一：升级主题版本 #

将sphinx_rtd_theme升级到适配Sphinx 5.x的版本，比如1.2.0及以上，依赖组合调整为：

docutils==0.16
sphinx==5.3
sphinx_rtd_theme==1.2.0

升级后主题能正常适配Sphinx 5.3的搜索功能，同时RST列表渲染不受影响。

方案二：回退到稳定旧环境 #

如果不想升级主题，可回到之前能用的低版本Sphinx，同时锁定sphinxcontrib.applehelp的旧版本，避免版本冲突报错。比如采用以下依赖组合：

sphinx==4.5
sphinx_rtd_theme==1.0.0
sphinxcontrib-applehelp==1.0.4

或者：

sphinx==3.5.4
sphinx_rtd_theme==1.0.0
jinja2==3.0.3
sphinxcontrib-applehelp==1.0.4

这样既能解决applehelp的版本报错，又能保留原有环境的所有功能正常运行。

内容的提问来源于stack exchange，提问作者Trdiaz