使用Python3.11 Sphinx 7.2.6生成的HTMLHELP文件无法使用hhc.exe编译

Question

我们的软件使用Sphinx来生成文档、网站、chm等... 我们正在尝试从 python2.7 切换到 python3.11 阻塞点之一如下： 我们运行

sphinx -b htmlhelp

，然后在输出上运行 hhc.exe 以生成 CHM。

这样做会引发以下错误并且 chm 已损坏

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

经过调查，我意识到生成的文件（.hhp、.hhc 等..）是不同的（sphinx 在相同的输入文件和相同的配置上运行）

特别是对hhc文件“}”中的一些特殊字符进行了编码。手动将它们更改回原始值似乎可以解决问题。 左：使用 python 2.7 创建的文件 --> 有效 右：使用 python 3.11 创建的文件 --> 不起作用

正确的文件名确实是

src/functions/@f{lastprintdate}.html

• 造成这种差异的原因是什么？

• 我做错了什么吗？

• 我是否缺少从 python2.7 到 python3.11 的配置更新？

Answer 1

请注意，专有的 CHM 文件格式已有大约 25 年历史，首次随 IE4 和 Windows 98 一起提供。

您知道 - HTML Help 1.x 编译器不兼容 Unicode，并且在编译包含非拉丁字符或特殊字符（例如 @、{、}、#、$、!、* 和等）的 CHM 时可能会失败路径和/或主题名称。 URL 百分比编码用“%”后跟两个十六进制数字替换特殊 ASCII 字符。

使用简单的主题文件，例如，可以重现错误。 @f{lastprintdate}.rst

，除了目录文件 *.hhc 的已知问题（在 Windows10 Pro、Python 3.11.4、Sphinx 7.2.6 上测试）之外，还出现在可选生成的索引文件 *.hhk 中。在

src\functions\@f{lastprintdate}.html

部分使用

[FILES]

生成的*.hhp工程文件就OK了。

*.hhc 示例：

<LI> <OBJECT type="text/sitemap">
    <param name="Name" value="Functions">
    <param name="Local" value="src/functions/%40f%7Blastprintdate%7D.html">
</OBJECT>

*.hhk 样本：

<UL> <LI> <OBJECT type="text/sitemap">
    <param name="Keyword" value="LastPrintDate">
    <param name="Local" value="src/functions/%40f%7Blastprintdate%7D.html#index-0">
</OBJECT>

HTMLHelp错误消息参考中针对HHC5013建议的解决方案也没有帮助，因为Sphinx已经默认设置了Binary TOC=No

！

HHC5013： TOC 错误：URL 引用无法解析“文件名” 问题：编译器无法为 HHC 文件中的条目创建 URL。如果编译器无法找到 HHC 中引用的文件，则可能会出现此问题。 结果： .chm 文件已损坏且无法使用。

这是Sphinx引起的问题，因为URL百分比编码替换。

在此阶段，我只看到避免使用带有特殊字符的文件名

或清理您的.hhc文件，就像您已经完成的那样（例如使用Notepad ++宏，脚本或RegEx）。