概述

这是Sphinx文档生成器的说明书，Sphinx是一个工具，它能够把一组 reStructuredText 格式的文件转换成各种输出格式，而且自动地生成交叉引用，生成目录等。也就是说，如果有一个目录，里面包含一堆reST格式的文档（可能子目录里面也同样存在reST格式的文档），Sphinx能够生成一个漂亮的组织结构以及便于浏览和导航的HTML 文件（这些文件在其他的文件夹中）。当然对于同样的来源文件（reST格式），它也能够生成一个能够被编译（生成）PDF版本的LaTeX格式的文件，或者直接使用 rst2pdf 生成PDF文件。

Sphinx注重的是人工的文档，而不是自动生成的API文档。尽管Sphinx或多或少地也支持自动生成的API文档，如果需要纯粹的API文档，可以看看 Epydoc （Epydoc也支持reST格式）。

转换其他文件系统

本节的目的是为给那些从其他文件系统迁移到reStructuredText/Sphinx上的人提供一些有用的提示。

• Gerard Flanagan写了一个从纯html格式到reST格式的脚本；这个脚本能在 Python Package Index 上被找到。
• 为了转换旧的Python文档到Sphinx，“转换器”在 the Python SVN repository 上。它包含了从python文档形式的LaTeX标记到Sphinx reST的代码。
• Marcin Wojdyr写了一个从Docbook到带有Sphinx标记的reST；它位于 Google Code。
• Christophe de Vienne 写了一个从Open/LibreOffice文件到Sphinx的转换工具： odt2sphinx。
• 为了转换不同的标记，Pandoc 是一个很有用的工具。

使用其他系统（工具）

请参看 Sphinx FAQ。

安装先决条件

• 对于Python 2，需要 Python 2.4 （或者以上版本）
• 对于Python 3，需要 Python 3.1 （或者以上版本）
• docutils （0.7或者SVN上的trunk版本） 和 Jinja2
• Pygments （如果需要代码高亮）
• uuid （如果使用 Python 2.4 ）

如何使用Sphinx

请参看 初入Sphinx。初入Sphinx 包含了手册里面很多高级的话题。