提高工作效率无论对个人还是对团队来说都至关重要。在开源技术文档项目中，维护文档仓库可能费时又费力。你可能需要：
- 对比两个 Git 分支中数百个文件，找出哪个分支多了哪份文件；
- 为上千份文件添加 metadata 摘要部分，以获得更好的搜索引擎优化效果；
- 找出文档目录 (TOC) 中遗漏添加了哪份文档；
- 为 Excel 表格某一列上百个单元格添加符合一定规则的超链接。
以上任务都需要大量机械重复劳动，极为繁琐耗时。如果人工手动去完成，工作效率会大打折扣。那么是否可以将这些繁琐工作自动化呢？是否有适合纯文科生上手的简单编程语言，让技术小白也能写一个简单的小脚本自动完成这些工作呢？
答案是有的，那就是当前大火的 Python。Python 语法简洁易懂，封装程度高，文科生不需要懂太多计算机底层知识，只需花两三个月时间，就可将前辈们已经造好的“车轮”组装成一辆自己的“车”了。
笔者就属于这类纯文科语言专业出身的技术文档从业者。面对费时费力的文档维护工作，我也毫不犹豫地跟着视频网站自学了三个月，组装出了一辆能开的“车”。
面向受众
本文面向英语、翻译等纯文科专业出身的技术文档从业者，或纯文科专业在读、想要从事技术文档写作的同学。总之，如果您有计算机或自动化教育背景的，可以忽略本文😁。
场景描述
笔者目前从事的开源技术文档项目中，大多数文档都在左侧目录导航中有入口，左侧目录导航如下图所示。
image.png
在 GitHub pingcap/docs-cn 仓库中，有一个叫 TOC.md 的文件。该文件为文档仓库的目录，所罗列的条目直接对应官网文档站左侧文档目录的条目。
image.png
该仓库共有 6 个分支需要维护，每个分支中有数百个 markdown 文件不等。并非每一个 markdown 文件都加到了这份 TOC.md 文件中。如果是哪篇文档漏加入了，那么用户便无法从官网文档站左侧找到文档入口，用户的内容旅程中直接缺失了应有的一环，那么文档的交付就不算完成。
找出目录中哪些 markdown 文件未在 TOC 目录中不是一件轻松的事儿。仓库中有数百个 markdown 文件，TOC 目录中也罗列有上百个文件。面对如此庞大的数量，平时简单的查找有无也变得不容易，当然，这是说人工手动识别查找。那么使用 Python 脚本又会如何呢？如何写出这样一个简单的小脚本呢？下面先来分析下我们的查找需求。
思路分析
在开始写 Python 脚本前，我们先来梳理下思路。要想找出哪些 markdown 文件未加入文档目录 TOC.md，需要进行以下过程：
-
获取 docs-cn 仓库下每一个 markdown 文件的文件名。
-
将每一个 markdown 文件名逐个匹配 TOC.md 目录中的所有条目。
- 如果匹配成功，说明该 markdown 文件已加入文档目录，不做任何处理，继续对下一个 markdown 文件进行匹配。
- 如果匹配失败，说明该 markdown 文件未加入文档目录，该文件就是我们要找寻的文件之一，将其记录下来。继续对下一个 markdown 文件进行匹配。
-
汇总所有未匹配到 TOC 条目的文件名，这些文件名就是我们最终想要找出的目标，我们便可以由此此判断是有意不加进文档目录，还是不小心遗漏的。
按照这个思路，便可以写出一个简单小脚本，具体的代码如下：
完整的脚本
import os
import re
# 得到仓库文件夹下所有 Markdown 文件的列表
md_files = []
for root, dirs, files in os.walk('<仓库路径>', topdown=False):
for file in files:
if file.endswith('.md'):
md_files.append(file)
# 得到 TOC 目录中所列的 Markdown 文件列表
toc_files = []
with open('<TOC 文件路径>', 'r', encoding='utf-8') as fp:
for line in fp.readlines():
if re.search('[-a-z0-9.]+\.md', line): # 假设文件名不包含汉字和特殊符号
toc_files.append(re.search('[-a-z0-9.]+\.md', line).group())
# 判断仓库中的 Markdown 文件列表是否在 TOC 目录中。如果某文件不在，则打印出文件名。
for md_file in md_files:
if md_file not in toc_files:
print(md_file) # 这就是我们要找的文件
短短十几行代码，入门级的 Python 知识，漏加入 TOC 目录的 markdown 文件便在数秒内悉数打印出来，解决的可是实打实的效率问题。
结语和建议
工欲善其事，必先利其器。如果你从事开源技术文档工作，同时面临繁重的维护工作，那可以考虑使用 Python 脚本来快速完成人工数小时甚至数天才能完成的机械重复性工作，大大提高工作效率。嗯，真香~
网友评论