像埃及人一样编写文档：使用 Sphinx 管理项目文档

图片来源

April Killingsworth。由 Rikki Endsley 修改。CC BY-SA 2.0。

在第 14 届年度南加州 Linux 展览会（又名 SCaLE 14x）上，Dru Lavigne 将讨论与创建和维护文档相关的常见“陷阱”，她还将介绍可用的开源工具。她还将概述 Sphinx，这是一个最初为新的 Python 文档创建的开源文档生成系统。

在本次采访中，她解释了 Sphinx 与其他开源解决方案的不同之处，以及哪些类型的项目应考虑迁移其文档。

为什么 PC-BSD、FreeNAS 和 Lumina 文档项目迁移到 Sphinx？

当我在 2010 年负责维护 PC-BSD 文档时，我继承了一个现有的文档 wiki，其中包含大量用户生成的内容，其中大部分内容已过时几年。此后不久，我也开始负责创建新的 FreeNAS 文档，因此为该项目制作文档 wiki 也是有意义的。

随着时间的推移，wiki 方法在维护更新和版本化文档方面的缺点变得显而易见

虽然 wiki 的主要目的是邀请用户贡献和提供低门槛的入门方式，但很少有人来编写文档（但是，地球上的每个垃圾邮件机器人都会很快找到你的 wiki，这会带来自己的一系列维护问题）。
Wiki 旨在用于独立的、一页左右的信息字节，例如操作指南。它们实际上并非旨在在目录中提供导航或提供章节流程，尽管你可以修改页面以提供导航元素以匹配文档流程。随着文档大小的增加，这变得更加困难——我们的指南往往超过 300 页。当你尝试为这些页面中的每一个提供版本化副本，以便用户找到并阅读适合其软件版本的正确页面时，这会变成一场噩梦。
虽然 wiki 翻译扩展程序可用，但如何配置它们没有很好的文档记录，它们的使用速度慢且笨拙，并且翻译后的页面只会增加可用页面的数量，使你回到上一个要点中的问题。对于拥有全球受众的项目来说，这是一个大问题。
虽然输出生成 wiki 扩展程序可用（例如，将你的 wiki 页面转换为 HTML 或 PDF），但如何配置它们没有很好的文档记录，并且它们为生成格式的布局提供的控制非常少。对于需要以多种格式提供文档的项目来说，这是一个大问题。

我们花了几年时间将各种变通方法添加到我们现有的 wiki 基础设施中，以说服它创建我们需要的：各种格式的大型、版本化、翻译文档。我们还花了很多时间研究替代方案。在研究时，我们牢记以下目标

必须支持目录结构，并且能够生成多种格式，最好是通过与源构建基础设施集成；
必须无缝集成到翻译基础设施中；
应为文档编写者和翻译人员提供低门槛的入门方式。

在我们的研究中，我们发现入门门槛往往与可用输出格式的质量和数量成反比。

Sphinx 提供了一个很好的中间地带，因为它的语法几乎与 wiki 语法一样容易学习，它支持集成到现有的源代码存储库以及构建和翻译基础设施中，并且它提供了对输出布局的合理控制，尽管这因格式而异。

从迁移到 Sphinx 中可以学到哪些重要的经验教训？

作为一项实验，我首先迁移了现有的 FreeNAS 文档。由于那时我们同时维护 wiki 和主 OpenOffice 文档（用于生成 HTML 和 PDF），我找到了一个将 .odt 转换为 .rst（Sphinx 使用的格式）的脚本。由于以前从未使用过 .rst 或 Python conf.py，我花了一些时间学习如何构建 HTML 版本并试验各种主题和扩展程序。然后我花了一个月左右的时间清理迁移后的 .rst 文件，边做边学各种标签的工作方式以及布局文档树的最佳方法。与任何迁移脚本一样，并非所有内容都干净地迁移，这让我有机会弄清楚表格的格式以及哪些标签控制哪些布局。

在第一次迁移之后，我对我们的文档使用了哪些标签、哪些扩展程序有用以及我们喜欢哪个主题有了很好的了解。然后我利用这些知识迁移了 PC-BSD 文档。这次我使用了不同的迁移脚本，它的标签略有不同。这让我有机会发现以前从未见过的标签，并决定我最喜欢哪些标签，以便在两个文档项目之间进行标准化。第二次迁移花了不到一周的时间。当我们需要 Lumina 文档项目时，我直接使用 Sphinx 创建了它，并且花不到一个小时就设置好了文档树、构建基础设施、主题和扩展程序，以便我可以从头开始编写文档。

在经历了此过程之后，我建议以下几点

如果你计划迁移现有的文档集，请为你当前的格式找到一个迁移脚本，并给自己时间来尝试标签、主题和扩展程序。
编写一个 README 文件，其中包含针对文档编写者和希望从你的文档源创建自己的格式的用户的说明。这应包括任何需要安装的软件以及你的文档项目使用的标签列表——在迁移结束时你就会知道这些是什么。

Sphinx 与其他开源解决方案有何不同？

虽然 Sphinx 易于学习，但它确实有其怪癖。例如，它不支持堆叠标签。这意味着，例如，你不能使用标签将短语加粗倾斜——要实现这一点需要 CSS 解决方法。而且，虽然 Sphinx 确实有大量的文档，但其中很多都假设你已经知道自己在做什么。当你不知道时，可能很难找到一个可以实现你想要实现的目标的示例。

Sphinx 非常适合具有现有存储库（例如，在 github 上）、构建基础设施以及熟悉使用文本编辑器并提交到存储库（或创建，例如，git pull 请求）的贡献者的项目。

对于那些希望在内置或可用主题之外控制文档外观的项目，访问 CSS 大师非常有用。

对于文档集较小且不需要版本控制、翻译或多种发布格式的项目来说，这可能有点过头了。

哪些项目以拥有出色的文档而脱颖而出？哪些项目将受益于文档大修？

多年来一直负责文档工作，我很犹豫指出文档的优缺点示例。对于任何项目来说，文档编写都是困难且耗时的。软件是一个移动的目标，软件用户的技能水平各不相同，因此，他们的文档需求也大相径庭。在这方面，没有文档是永远完成的——或者真正最新的——这只是文档工作的本质。我们能做的最好的事情是努力使贡献者更容易、更愿意协助保持文档的更新、有用，并以软件用户群体所需的语言和格式提供。