Python3.11 Sphinx生成的HTMLHelp文件无法用hhc.exe编译问题咨询

问题场景 #

我们的软件通过Sphinx生成文档网站及CHM文件，在从Python2.7迁移至Python3.11的过程中遇到阻塞问题：执行sphinx -b htmlhelp生成文件后，使用hhc.exe编译生成CHM时出现如下错误，导致CHM文件损坏：

HHC5013: Error:
runtime error R6002
- floating point not loaded

经排查发现，相同输入及配置下，Python3.11版本Sphinx生成的.hhp、.hhc等文件与Python2.7版本存在差异，尤其是.hhc文件中的特殊字符“}”被编码。手动将其改回原始值后问题可解决，正确文件名应为src/functions/@f{lastprintdate}.html。

1. 差异产生的原因 #

• Python版本的字符串编码逻辑差异：Python2默认采用ASCII编码，字符串处理较为宽松；Python3默认使用UTF-8，且内部字符串处理机制更严格。Sphinx适配Python3时，调整了对文件名中特殊字符（如}）的转义规则，导致原本不需要编码的字符被转义，生成hhc.exe无法识别的路径格式。
• Sphinx版本迭代的逻辑变化：迁移到Python3时必然升级了Sphinx版本，新版本的htmlhelp生成器修改了CHM相关文件（.hhp/.hhc）的路径生成逻辑，对特殊字符的处理策略改变，进而触发hhc.exe的兼容性错误（hhc.exe对非预期的路径字符容错性较低）。

2. 是否存在操作失误？ #

不存在操作失误。该问题是在相同输入、配置下仅切换Python版本后出现的，且手动修复编码字符即可解决，说明根源是版本迭代带来的逻辑变化，而非操作步骤错误。即使迁移时正确升级了适配Python3的Sphinx版本，也会因编码逻辑差异遇到此问题。

3. 是否遗漏了配置更新？ #

大概率是遗漏了针对CHM生成的特殊配置：

• Sphinx在Python3版本中新增了控制路径转义/编码的配置项，需在conf.py中添加或调整相关参数（例如与路径处理、字符转义相关的设置），禁用对}这类特殊字符的编码。
• 检查conf.py中是否残留Python2特有的兼容配置（如sys.setdefaultencoding('utf-8')），这类代码在Python3中无效，可能间接影响Sphinx的字符处理逻辑，需移除或替换为Python3兼容的配置。

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