Pixabay License
写软著是一个神奇的工作,最后还要将一些实际代码粘贴到 word 文档中,这种繁琐的工作怎么能手动搞呢,python 脚本走起来。
需求
一股脑粘贴上所有代码即可,不用解释不用组织,字号小点一页50行以上即可。当然像我介么优秀的程序猿要考虑得更通用一点:
代码加个语法高亮,支持大多数语言。
可以自定义需要收集的文件的扩展名
可以设置哪些文件或目录需要忽略,有一些带密码或者私有 key 的源文件不能放。
可以限制行数
技术方案
既然要生成 word 文档,先搜了一下 python 生成 docx 格式的库,果然有,就叫 python-docx。简单试了一下,直接生成没有语法高亮的文档很简单,如果要语法高亮就要调用各种 API 来添加格式化的文本。
再搜了一下语法高亮的库,果然也有,Pygments,支持几乎所有语言,看示例代码也很简单。简单说一下原理:Pygments 支持多种语言,需要先判断代码文本的语言,然后根据语言选择词法分析器 lexer,文本通过语法分析器的处理得到结构化的 token 流,再选择一种 formatter 来输出语法高亮的代码。lexer 跟源代码的语言相关,Pygments 支持几乎所有语言,只用考虑怎么判断语言就行。formatter 的支持种类有限,有 html、pdf、各种图片等……就是没有 docx。
理论上可以通过 python-docx 库来自定义 formatter 自行实现一个 docx 的版本,Pygments 对自定义 formatter 支持得很好……但工作量比较大,不是一两天能搞定的。最后选择生成 html,最后一步 html 转到 docx 通过手动进行——看起来比较 low,实际上我还调研了一些自动转换方法:
调用 web 服务接口转换:一些免费的在线工具可以在网页上免费用,调用接口就需要购买了,免费额度比较少,还必须联网。
还有一个叫 pandoc 的库可以转换,但是不支持 style 的转换,语法高亮没了。
Word 能直接打开 html 文件,只需要「另存为」一下就可以转换成 docx,不需要额外工具。因此,最后决定还是转换为 html,再手工转换为 word。
代码
脚本已放到 Github 上了:codes2html,直接可用。下文解析一下关键代码。
argparse 自定义参数
有一些参数需要配置,因此使用了 argparse 库来定义和解析参数,这个库非常强大,只需定义好参数,help 信息能自动生成。看下面的例子:
import argparse
parser = argparse.ArgumentParser(description='A tool to collect codes and highlight syntax in a single html document.')
parser.add_argument('sources', # 无前缀参数
metavar='source', # 显示在 help 中的名字
nargs='+', # 指定该参数数量,"+" 表示至少一个,还可以设置具体数量
help='source code directory or file') # help 信息
parser.add_argument('-o', '--out', # 可以指定多个名字,哪个都可以
help='output file path. default is output.html',
default='output.html', # 设置默认值
dest='output') # 代码中的标识符,如果不写就用前面参数名称 ”--out“ 指定的 "out"
parser.add_argument('--insert-file-name', help='insert file name as header of a file',
action='store_true',
# 这个 store_true 表示出现这个 '--insert-file-name' 参数
# 就将 .insert_file_name 设置为 True
dest='insert_file_name')
args = parser.parse_args()
args.source # list of str
args.output # str
args.insert_file_name # bool
使用 add_argument() 方法来定义参数,这个方法参数比较多,一般有几种类型的参数:
不需要 -x 或 --xxx 这类前缀的参数,一般当做主要参数。
指定 -x 或 --xxx 前缀的参数,一般当做可选参数,并提供默认值。
使用 -x 或 --xxx 作为开关。
遍历目录、extensions 参数、ignore 文件
遍历目录有几种方法:glob.glob,os.walk,os.listdir。前面两个都是自动递归遍历。os.listdir 需要自己递归调用,由于需要遍历到 ignore 的目录时能终止其子目录的遍历,使用 os.listdir 看起来比较清晰一点。
extensions 参数指定哪些扩展名可以作为源文件。
ignore 文件使用类似 .gitignore 语法:按行分割成一个匹配字符串列表,作为 ignore 规则。遍历过程中如果一个文件匹配了 ignore 规则,直接将这个文件忽略;如果一个目录匹配了 ignore 规则,忽略它并且不进入其中遍历,也就是忽略所有的子目录和文件。
class Codes2HtmlTool:
def _collect_files(self, path):
subfiles = os.listdir(path)
subfiles.sort() # 按字母顺序排个序
for subfile in subfiles:
if self.written_lines >= self.args.lines: # 行数限制判断
break
if subfile.startswith('.'): # 隐藏目录直接忽略
continue
full_path = os.path.join(path, subfile)
# 调用 _should_ignore_file 方法判断是否需要忽略
if self._should_ignore_file(subfile):
print('ignore "', full_path, '"', sep='')
continue
if os.path.isdir(full_path): # 如果是目录,递归调用
self._collect_files(full_path)
elif self._accept_extension(subfile): # 如果是文件,还要检查扩展名
# 如果扩展名符合,调用文件处理方法
self._highlight_and_write_file(full_path)
def _should_ignore_file(self, name):
return _match_any_pattern(name, self.args.ignore_patterns)
def _accept_extension(self, name):
patterns = self.args.extension_patterns
# 没有 patterns 表示对扩展名没有限制
return len(patterns) == 0 or _match_any_pattern(name, patterns)
def _match_any_pattern(name, patterns):
for pattern in patterns:
if fnmatch.fnmatch(name, pattern):
return True
return False
语法高亮
Pygments 其实还可以生成 rtf 格式的文档,它比 html 更接近 docx,因为 word 软件会自动关联 rtf 扩展名。但经过调研发现 Pygments 对 rtf 格式的处理没有 html 灵活,rtf 文件头中的样式定义没有剥离开,多个文件格式化拼接到一起比较麻烦。Pygments 的 html formatter 将 css 定义单独抽象出来,并提供了只返回引用 css 的 html 片段,适合多个文件使用同一配色方案拼接成一个大文件的场景。
from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import get_lexer_for_filename
# hf - HtmlFormatter
class Codes2HtmlTool:
def _highlight_and_write_file(self, full_path):
write_fd = self.write_fd
hf = self.hf
footer = self.args.file_footer
try:
# 先根据文件名获取 lexer,如果无法识别为源代码会直接抛异常
lexer = get_lexer_for_filename(full_path)
with open(full_path) as fd:
lines = fd.readlines()
self.written_lines += len(lines)
content = ''.join(lines)
if full_path.endswith('.h'):
# 如果是 ".h" 文件,根据内容再次判断一下
lexer = get_lexer_for_filename(full_path, code=content)
formatted = highlight(content, lexer, hf) # 高亮代码返回格式化代码
write_fd.write(formatted) # 写入格式化的代码
write_fd.write(footer) # 写入参数中定义的 footer
print('highlighted with ', _short_class_name(lexer), ': "', full_path, '"', sep='')
except:
# 如果正确设置了 extensions 参数,异常情况应该很少出现
print('not source code: "', full_path, '"', sep='')
猜测代码语言,可以通过文件扩展名,也可以通过文件内容。比较有趣的是 .h 文件只通过扩展名,会判定为 C 语言。但 Objective-C 也使用 .h 文件,而且 Objective-C 是 C 的超集,有一些 C 中没有的语法,如果只用文件名,就会导致一些语法解析错误,不能正确高亮。同时使用文件名和文件内容判断才可以正确判定使用的是 Objective-C 还是 C。
用法简介
需要 python3
需要安装 Pygments pip install Pygments
最简单用法:python codes2html.py [目录],会遍历指定的目录,收集 3500 行代码到一个单独的 html 文件中。
参数 -e, --extensions:限定源代码文件扩展名,用逗号分割的字符串,如果不限制可以传 "*" 或者不写。默认值 "*"。
参数 -l, --lines:限制读入的源代码行数,但不会截断一个完整的文件,所以最终行数可能会大于这个值。0 表示不限制行数。默认值 3500。
参数 -o, --out:指定输出的 html 文件名。默认值 output.html
参数 -i, --ignore:指定 ignore 文件。默认值 ignore.txt
参数 -f, --footer:指定每个文件末尾插入的内容,HTML 格式字符串。默认值 。
举个例子
python codes2html.py ~/texthere/ ~/next/ -e h,c,cpp,m,mm,swift -l 5000 -i xcode_ignore.txt -o all_ios_projects.html
ignore 文件示例,iOS 项目
Pods
Assets.xcassets
*.framework
AppDelegate.*
(ole)