Sphinx 如何制作 Windows .chm 帮助文档
chm 帮助文档
前言
对于一些人来说，sphinx 这个名词可能有些陌生。但是，你可能在某些地方见过上图中的这种文档。sphinx 是 python 的一个第三方库，用于构建文档，并且方便快速地将文档转换成各种类型。同时，还可以和 Read The Docs 网站搭配，实现文档推送和自动更新等功能。markdown 可能是很多人更加经常使用的标记语言，而 sphinx 使用的是另一种标记语言：reStructuredText
使用 sphinx 可以生成本机上可以阅读的 html 文档。但是有时候文档编写到一定程度后，想分享给他人，可以考虑将文档打包成单机的 .chm 文档。本文将介绍这一部分。
写作目的
如何从 Sphinx 基础文件中构建生成出单机版的 Windows 帮助文件。
本文不包括：Sphinx 文档基础文件的构建(......)，可以自己通过搜索引擎查找相关介使用绍。附上上图的 Read The Docs 链接：Sphinx 学习笔记
当你用过 sphinx 或者想自己构建一些类似上图中的文档时，本文或许值得一看。
正文
sphinx 文件结构
从此部分开始说明。
在当前路径下打开 console 窗口，运行
make htmlhelp
可以在上面的 build 文件夹中看见生成的 htmlhelp 的基础文件。
htmlhelp 基础文件
而将这些基础文件打包生成一份 .chm 文档，需要用到 Microsoft 的 HTML Help Workshop 软件，这个软件在微软官网上的链接不知为何挂掉了。这里有讨论(HTMLHelp Workshop - download for CHM compiler installation failed)，也有人给出 Internet Archive 的储存链接。单纯复制一个下载地址，如果觉得不安全，请到上述讨论中找到他给的地址进行下载。
HTML Help Workshop
使用该软件打开上面生成的 .hhp 文件，不能直接将这个文件拖进去。
打开配置文件
按钮1: 你可以在这个按钮里面看到 button 选项卡，可以控制 .chm 文件最上方的按钮，比如增加刷新按钮。
按钮2: 保存所有文件，编译生成文件。
另外的其他配置可以自行尝试更改。确定都更改完成以后，点击按钮2就可以了。
结果
可以看到已经生成了我们想要的文件。一般到这一步就算完成了。
(注：目标文件打开状态下是无法生成的，这一点需要注意。)
这一步完成后，你可能发现有一些问题。比如点击 .chm 文件的字体按钮，字体无法改变。
通过尝试，我发现是和使用的 Sphinx 主题有关系。有部分主题的字体是写死的，正常情况下无法改变大小。比如写了
font-size: 15px;
font-size: 1em;
这种。这部分都在上面图片中的 _static 文件夹中都可以找到。
既然知道问题所在，那么修复起来也很简单了。我自己是写了一个脚本，直接删除掉该文件夹中每个 .css 文件中包含有类似上面将字体写死的代码行就可以了(将脚本做成命令行形式，后续需要的时候将目标路径拖进去跑一下就行)。删除掉之后重新点击按钮2 再生成一个新的文档，这个新的文档就能正常使用字体的扩大和缩小。
顺便将脚本也放在这里吧。
import argparse
import os
import re
parser = argparse.ArgumentParser(
description='remove font size in css file'
)
parser.add_argument('path', help='css directory path')
args = parser.parse_args()
path = os.path.abspath(args.path)
if not os.path.exists(path):
raise SystemExit(f'Path not exists: [{path}]')
for root, dirs, files in os.walk(path):
for file in files:
if not file.endswith('.css'):
continue
filepath = os.path.join(root, file)
with open(filepath, 'r', encoding='utf-8')as fl:
data = fl.read()
data, n = re.subn(r'[ ]+font-size: .*?(?:px|em);\n?', '', data)
if n == 0:
continue
with open(filepath, 'w', encoding='utf-8')as fl:
fl.write(data)
flag = 'part' if n == 1 else 'parts'
print(f'[{filepath}] {n} {flag} changed!')
将上面的代码保存到文件 removeFontSize.py 里面，使用方式就是：
在脚本所在路径下打开 console 窗口，通过
python removeFontSize.py <path>
敲 python removeFontSize.py 加一个空格，然后把目标路径拖进去，Enter 就可以了。python 版本要 >=3.7
这些说明是不是太过于多此一举？？？
大概到这里才算大功告成吧。
