本文共 2387 字,大约阅读时间需要 7 分钟。
sphinx 文档
在第14届年度南加州Linux Expo(又名SCaLE 14x)上, 与创建和维护文档有关的常见“陷阱”,她将讨论可用的开源工具。 她还将概述 , 是最初为创建的开源文档生成系统。
在这次采访中,她解释了Sphinx与其他开源解决方案的不同之处,以及应考虑迁移哪种类型的项目的文档。
当我在2010年负责维护 ,我继承了一个现有的文档Wiki,其中包含许多用户生成的内容,其中大多数已过时。 此后不久,我还负责创建新的 ,因此也有必要为该项目创建文档Wiki。
随着时间的流逝,Wiki方法用于维护更新和版本化文档的缺点变得显而易见:
我们花了几年的时间将各种各样的问题打入我们现有的Wiki基础结构中,以说服它创建我们所需的内容:各种格式的大型,版本化,翻译后的文档。 我们还花费了大量时间来研究替代方案。 在研究时,我们牢记以下目标:
在我们的研究中,我们发现进入壁垒往往与可用输出格式的质量和数量成反比。
Sphinx提供了一个良好的中间立场,因为它的语法几乎与Wiki语法一样容易学习,它支持集成到现有的源存储库以及构建和翻译基础结构中,并提供对输出布局的良好控制,尽管这取决于格式。
作为实验,我首先迁移了现有的FreeNAS文档。 从那时起,我们既维护了Wiki又维护了OpenOffice主文档(用于生成HTML和PDF),因此我找到了一个脚本,可将.odt转换为.rst(Sphinx使用的格式)。 以前从未使用过.rst或Python conf.py,我花了一些时间学习如何构建HTML版本并尝试各种主题和扩展名。 然后,我花了大约一个月的时间来清理迁移的.rst文件,一边学习各种标签的工作方式,一边学习整理文档树的最佳方法。 与任何迁移脚本一样,并不是所有内容都迁移得很干净,这使我有机会弄清楚表的格式以及哪个标签控制哪种布局。
在第一次迁移之后,我对我们的文档使用了哪些标签,有用的扩展以及我们喜欢的主题有了很好的了解。 然后,我使用这些知识来迁移PC-BSD文档。 这次,我使用了一个不同的迁移脚本,该脚本的标签稍有不同。 这使我有机会发现以前从未见过的标签,并决定最喜欢的标签以便在两个文档项目之间进行标准化。 第二次迁移用了不到一周的时间。 当我们需要Lumina文档项目时,我直接使用Sphinx创建了它,并且花了不到一个小时的时间来设置文档树,构建基础结构,主题和扩展,以便我可以从头开始编写文档。 。
完成此过程后,我将建议以下内容:
虽然狮身人面像很容易学习,但它确实有其怪癖。 例如,它不支持堆叠标签。 例如,这意味着您不能使用标签将单词加粗斜体-要实现这一点需要CSS解决方法。 而且,尽管Sphinx确实有大量的文档,但是其中很多假设您已经知道自己在做什么。 如果不这样做,可能很难找到一个可以实现您想要达到的目标的示例。
Sphinx非常适合具有现有存储库(例如在github上)的构建基础结构的项目,以及对使用文本编辑器和提交存储库(或创建例如git pull请求)感到满意的贡献者。
对于那些希望通过内置主题或可用主题来控制文档外观的项目,访问CSS专家很有用。
对于文档集很小,不需要版本控制,翻译或多种发布格式的项目而言,这可能是多余的。
在负责文档工作多年之后,我不愿指出文档的好坏示例。 任何项目的文档编制工作都很繁琐且耗时。 软件是一个不断发展的目标,软件用户的技能范围很广,因此文档需求也大不相同。 在这方面,没有任何文档可以完成或真正地是最新的,而这仅仅是文档游戏的本质。 我们所能做的最好的就是设法使投稿人容易且引人注目,以帮助他们使文档保持最新,有用,并以软件用户群所需的语言和格式。
所有闪亮的新
docs,像上衣一样闪闪发光 金字塔。翻译自:
sphinx 文档
转载地址:http://ypnzd.baihongyu.com/