sphinx 文档_像埃及人一样的Doc：使用Sphinx管理项目文档

sphinx 文档

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

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

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

当我在2010年负责维护PC-BSD文档时 ，我继承了一个现有的文档Wiki，其中包含许多用户生成的内容，其中大多数已过时。 此后不久，我还负责创建新的FreeNAS文档 ，因此也有必要为该项目创建文档Wiki。

随着时间的流逝，Wiki方法用于维护更新和版本化文档的缺点变得显而易见：

• 虽然Wiki的主要目的是邀请用户贡献并降低进入门槛，但是很少有人来撰写文档（但是，地球上的每个垃圾邮件机器人都会Swift找到您的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创建了它，并且花了不到一个小时的时间来设置文档树，构建基础结构，主题和扩展，以便我可以从头开始编写文档。 。

完成此过程后，我将建议以下内容：

1. 如果计划迁移现有文档集，请查找当前格式的迁移脚本，并给自己时间来玩标签，主题和扩展名。
2. 写一个自述文件，其中包含文档编写者和想要从您的文档源创建自己的格式的用户的说明。 其中应该包括需要安装的所有软件以及doc项目使用的标签列表-您将在迁移结束时知道这些是什么。

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

虽然狮身人面像很容易学习，但它确实有其怪癖。 例如，它不支持堆叠标签。 例如，这意味着您不能使用标签将单词加粗斜体-要实现这一点需要CSS解决方法。 而且，尽管Sphinx确实有大量的文档，但是其中很多假设您已经知道自己在做什么。 如果不这样做，可能很难找到一个可以实现您想要达到的目标的示例。

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

对于那些希望通过内置主题或可用主题来控制文档外观的项目，访问CSS专家很有用。

对于文档集很小，不需要版本控制，翻译或多种发布格式的项目而言，这可能是多余的。

哪个项目具有出色的文档能力？ 哪些将从文档检修中受益？

在负责文档工作多年之后，我不愿指出文档的好坏示例。 任何项目的文档编制工作都很繁琐且耗时。 软件是一个不断发展的目标，软件用户的技能范围很广，因此文档需求也大不相同。 在这方面，没有任何文档可以完成或真正地是最新的，而这仅仅是文档游戏的本质。 我们所能做的最好的就是设法使投稿人容易且引人注目，以帮助他们使文档保持最新，有用，并以软件用户群所需的语言和格式。

我的愿景是：2016年将是开源Haiku年。 通过haiku，您有什么文档建议？

所有闪亮的新
docs，像上衣一样闪闪发光
金字塔。

翻译自: https://opensource.com/business/16/1/scale-14x-interview-dru-lavigne

sphinx 文档