为什么 Sphinx 和 reStructuredText ？

关于文档的第一个流派，就是我们现在用瓦尼什语订阅的一个流派：“文档编排……”它对任何人都不起作用。

第二个流派是“编写一个{La}TeX文档”流派，文档被视为独立的产品，它是独立生产的。这对PDF输出效果很好，但对HTML和TXT输出效果很差。

第三种流派是“识字编程”流派，它放弃了 both 程序源代码 and 文档源，这似乎是人们可以对两者的源代码施加的最好的访问保护之一。

第四个流派是“DoxGen”流派，它允许程序收集超链接变量、过程、类和文件名的无意识列表，并将其称为“文档”。

第五个流派是任何使用不能放入版本控制系统中的文件格式的东西，因为它是二进制的和不可比较的。无论是OpenOffice、LyX还是Word，无差异的文档源都不适合程序员。

坦率地说，这些在实践中都没有很好的效果。

一个非常核心的问题是，编写文档不能成为编程的大而明确的上下文切换。这就排除了基于浏览器的特殊图形编辑器(维基！)格式等

是的，如果你在工作日的一半时间里写文档，这是可行的，但如果你在工作日的大部分时间里写代码，那就不起作用。在这一点上相信我，我有25年避免使用这类工具的经验。

我发现有一个项目对这个问题进行了彻底的思考，他们的推理很有趣，对我很有吸引力：

  1. TXT文件是计算机的通用语言，即使您使用基于禽类运营商的IP Telnet登录(这在挪威比您想象的更普遍)，您也可以阅读.TXT格式的文档。

  2. TXT是限制最严格的排版格式，因此与其尝试将高级格式中性化为.TXT，更明智的做法是将.TXT作为源代码，并从结构上将其重新解释为功能更强的格式。

换句话说：我们谈论的是 ReStructuredText 对象包装的、由 Sphinx 项目。

除非有什么东西我完全没有注意到，那就是Varnish中的新文档平台。

浏览一下Python文档，然后尝试按下左侧菜单底部的“show source”链接：

(指向随机 Python 文档页面的链接：)

就依赖关系而言，这意味着您无需特殊工具即可编辑文档，您需要使用python+docutils+sphinx来格式化HTML和LaTeX(pdflatex？)生成PDF，这是我只希望在项目服务器上定期发生的事情。

我可以接受这一点，在这种情况下，我甚至可能会将VCC脚本从TCL重写为Python。

保尔-亨宁，2010-04-11