LWN：像对代码一样处理文档！

关注了就能看到更多这么棒的文章哦～

Treating documentation as code

February 26, 2024
This article was contributed by Koen Vervloesem
FOSDEM
智谱 AI translation
https://lwn.net/Articles/963037/

在FOSDEM 2024大会上，"Tool the docs" devroom举办了几场关于编写、管理、测试和渲染文档的自由且开源工具的讲座。其核心概念是将文档视为代码，这使得将各种工具整合到文档工作流程中，以保持高质量成为可能。

软件开发最佳实践之一是为项目设置持续集成（CI）。通过在每次提交到项目仓库的代码变更时自动运行格式化程序（formatter）、代码检查器（linter）和测试程序，开发者可以保持代码质量的统一。在题为Open Source DocOps的讲座中，Lorna Jane Mitchell 提出了将同样的方法应用于文档项目的观点。

这种 DocOps 方法，全称“文档操作（documentation operations）”，源自著名的DevOps定义，其定义是一组“实践、工具和文化哲学，这些实践和工具可以自动化和整合软件开发与 IT 团队之间的流程”。DocOps 不是将这些东西应用在软件开发中，而是应用于文档上。Mitchell 将 DocOps 描述为“使得文档能够以协作和高效的方式创建、维护和发布”。

将文档视为代码

DocOps 基于 Docs-as-code 的方法，该方法规定文档应以与代码相同的方式进行编写。Mitchell 强调了从软件开发中借鉴的工具和技术的重要性：

在许多文档工作流程中，使用 Git 至关重要，用基于文本的标记语言编写文档，然后将其转换为 HTML 或其他格式，简化了将文档整合到源代码控制中的过程。

Docs-as-code 的其他关键方面包括使用持续集成进行自动化测试以及使用本地工具运行相同的测试。"如果你需要将文档更改推送到 Git 中，以查看测试是否成功，那就不对了"，Mitchell 说。这个过程应该是快速且丝滑的。

为了对这一点进行说明，Mitchell 强调所有文档编写者都应该能够立即预览看到他们的改动。她展示了 Visual Studio Code 中的一个OpenAPI API 描述的例子。文档的 YAML 源文件位于左侧，右侧是生成的文档实时预览。"编写者在处理文档时需要这种即时反馈。"

另一个不可或缺的工具是链接检查器（link checker）。许多文档包含了指向网站的链接，这些网站可能会改变内部结构或下线，导致这些链接不再生效。链接检查器会自动访问文档中的所有链接，并验证它们是否仍然有效。有两种实现方法：一种是在源格式中检查链接，另一种是在生成的 HTML 文件中检查。"哪种方法都是有效的"，Mitchell 说，"我喜欢用 mlc 检查 Markdown 文件中的链接，但你也可以在构建过程后运行 HTML 链接检查器。"她提到的是 MIT 许可的标记链接检查器（Markup Link Checker）。

然而，Mitchell 警告说不要盲目使用链接检查。如果持续集成流水线有严格的链接检查，并且每次遇到断裂链接都会中止文档构建过程，那么当网站遇到临时下线时，可能会导致一些意外问题："不要让其他人的停机状况来阻碍你的构建或发布。"她提出了一些可以在这方面提供帮助的策略。例如，限制链接检查的范围："或许只需检查内部链接，或只检查更改的源文件中的链接。"为了找到所有失效的链接，Mitchell 建议每周安排一次全面的链接检查。

验证、格式化和文本检查（Validation, formatting, and prose linting）

与编程语言一样，标记语言也有应遵循的语法。但文档源文件中的标记错误在查看实时预览时可能不太看得出来。因此，任何文档工作流程都需要一些验证。对于 Markdown，Mitchell 推荐 David Anson 开发的 MIT 许可的markdownlint（还有其他同名工具存在）。"markdownlint 可配置非常强。对于 reStructuredText，Sphinx文档生成器包括了一个检查器。"Mitchell 的雇主Redocly开发了一个针对 OpenAPI 文档的 MIT 许可的检查器Redocly CLI。

检查源文件以确保语法有效是一方面，但哪怕文件确保有效了，也要考虑许多种编写内容的方式的差异。格式化器（formatter）可以帮助维持源文件之间的一致风格。"格式化器调整诸如换行符、间距、缩进、行长度以及项目符号列表和表格的一致语法等"，Mitchell 解释说。"使用一致的标记使你在源文件中查找问题变得容易得多。"

当然，除了标记语言，文本中使用的自然语言显然也很重要。其他工具可以帮助确保文本的质量，例如 Vale。Vale 可以帮助文档编写者捕捉写作中的常见错误，例如重复的词语和拼写错误，但它能做的远不止这些。Mitchell 指出，"Vale 特别适用于检查产品名称的正确大小写和拼写的使用是否一致"。关于 Vale，后续 LWN 文章会有文章发布。

无论项目使用哪些工具来处理其文档，Mitchell 都强调了它们应该无缝集成到团队的流程中："将它们整合到你的工作流程中，并确保所有用户在所有地方都使用相同的工具和配置。"为了保持文档质量，她建议在每次拉取请求时都用上这些工具，确保工作流程不会错过任何检查。"此外，在任何 pull request 上构建预览以帮助审阅者"，她补充说。

发起一个 pull request 是一个大范围的反馈循环。Mitchell 重申，文档编写者也需要小型化的反馈循环。"他们需要所有工具都可用在本地，理想情况下完全集成到他们的 IDE 中。"当然，本地环境里需要用户安装工具。因此，Mitchell 警告说，所有文档工具的设置步骤都应该清晰地写下来，方便今后新来的文档编写者。

文档编写中一些有用的工具

在 Mitchell 的介绍性讲座为后续内容奠定了基础后，其他的几场讲座深入探讨了文档编写者的一些有用的工具。Grafana Labs 的软件工程师 Jack Baldry解释了他的公司如何使用Vale来统一 Grafana 文档的风格：

如果你在你的文档中有规范使用 style guide，其实很难记住每一条规则。Vale 通过标记它检测到的任何违背规则的地方并且提供清晰的解释来帮助作者。

该公司的Writers' Toolkit实现了一些规则，当作者使用“模态（model）”而不是“对话框（dialog box）”等术语、使用将来时态而不是现在时、或者写“alert manager”而不是正确的“Alertmanager”时，都会显示一条消息。

文档不仅包含文本，还经常使用图表或其他图片。在嵌入式系统公司 Mind 工作的电气工程师 Frank Vanbever 描述了Gaphor如何支持文档编写者创建图表：

解释复杂系统的自然方式一直是走向白板并开始画框图和箭头。Gaphor 允许编写者在他们的文档中采用类似的过程。"

这个 Apache 2-licensed 软件实现了 UML、SysML、RAAML 和 C4 建模语言，允许文档编写者使用框图、状态机、软件架构图以及其他软件的可视化。

Gaphor 还可以与 Sphinx 文档生成器集成起来，使得文档构建系统可以在源模型更改时自动更新文档中的图表。此外，该工具带有 Python API，允许使用pytest进行模型测试，并且可以进行交互式地尝试，例如用在JupyterLab的基于 web 的开发环境中。

devroom 里最后介绍的工具是 Anton Zhiyanov 的 Apache 2-licensed 工具 codapi。Percona的 Peter Zaitsev 演示了如何使用 codapi 添加可嵌入的代码游乐场，使教程和操作指南变得互动。传统文档只是展示了一些示例代码及其结果，而使用 codapi 后，代码片段变成了一个动态的、可运行的内容。一旦读者点击运行按钮，代码就会运行并在 HTML 页面上更新输出。读者甚至可以编辑代码片段且重新运行来探索差异。

Codapi 有两个实现：一个是完全基于浏览器的，另一个是后台使用 Docker 容器的版本。第一个实现使用WebAssembly在沙箱执行环境中完全在浏览器内运行 Python、PHP、Ruby、Lua 或 SQLite 代码。第二个实现则是连接到服务器上的Docker容器，可以采用其他语言环境来运行。

结论

Mitchell 的演讲强调了将软件开发中的各种最佳实践应用于文档工作流程的优势。此外，“Tool the docs”为文档编写者提供了这个领域中各种可用 FOSS 工具的全面概述。希望这将帮助软件项目将这些工具添加到他们的工作流程中。每个项目都可以从一致、高质量的文档中受益。

全文完
LWN 文章遵循 CC BY-SA 4.0 许可协议。

欢迎分享、转载及基于现有协议再创作～

长按下面二维码关注，关注 LWN 深度文章以及开源社区的各种新近言论～