简介

这是Sphinx文档构建器的文档。Sphinx是一个工具，它将一组reStructuredText源文件转换为各种输出格式，自动生成交叉引用、索引等。也就是说，如果你有一个目录包含一堆reST格式的文档（以及可能的文档的子目录也在那里），Sphinx可以生成一个组织很好的HTML文件布局（在其他目录中），以方便浏览和导航。但是从同一个源，它也可以生成一个LaTeX文件，再将其编译为PDF版本的文档，或直接使用rst2pdf生成PDF文件。

其重点是手写文档，而不是自动生成的API文档。虽然也支持这种文档（这是为了自由地与手写内容混合），如果你需要纯粹的API文档看看Epydoc，它也理解reST。

对于编写文档的一个很好的“介绍” —— 为什么以及如何，另见由Eric Holscher写的编写文档。

从其他系统转换

本节旨在为希望从其他文档系统迁移到reStructuredText/Sphinx的用户收集有用的提示。

• Gerard Flanagan编写了一个脚本来将纯HTML转换为reST；它可以在Python包索引中找到。
• 要将旧的Python文档转换为Sphinx，可以在Python SVN存储库中找到一个转换器。它包含将Python文档类型的LaTeX标记转换为Sphinx reST的通用代码。
• Marcin Wojdyr写了一个脚本，将Docbook转换为带有Sphinx标记的reST；它位于Google Code。
• Christophe de Vienne编写了一个工具，用于将Open/LibreOffice文档转换为Sphinx：odt2sphinx。
• 要转换不同的标记，Pandoc是一个非常有用的工具。

用于其他系统

请参阅常见问题列表中的相关部分。

先决条件

Sphinx至少需要运行Python 2.7或Python 3.4以及docutils和Jinja2库。Sphinx应该使用docutils版本0.10或一些SVN分支的快照（不要是损坏的）。如果你喜欢有源代码高亮显示支持，你还必须安装Pygments库。

用法

有关介绍，请参见使用Sphinx的第一步。它还包含本手册中讨论的主题的更高级部分的链接。