介绍

这是Sphinx文档构建器的文档。 Sphinx是一个工具,它将一组 reStructuredText 源文件转换为各种输出格式,自动生成交叉引用,索引等。 也就是说,如果你有一个目录包含一堆reST格式的文档(也可能是那里的docs子目录),Sphinx可以生成一个组织良好的HTML文件排列(在其他目录中),以便于浏览和导航。但是从相同的来源,它也可以使用LaTeX生成PDF文件。

重点是手写文档,而不是自动生成的API文档。 虽然也支持这种文档(可以与手写内容自由混合),如果你需要纯API文档,请查看 Epydoc ,它也理解reST。

对于编写文档的一个伟大的”介绍” – 一如既往,请参阅Eric Holscher编写的 编写文档

从其他系统转换

本节旨在为那些想要从其他文档系统迁移到 reStructuredText/Sphinx 的人收集有用的提示。

  • Gerard Flanagan编写了一个脚本,将纯HTML转换为reST;它可以在 Python包索引 找到。
  • 为了将旧的Python文档转换为Sphinx,编写了一个转换器,可以在 Python SVN存储库 中找到。它包含将Python-doc样式的LaTeX标记转换为Sphinx reST的通用代码。
  • Marcin Wojdyr编写了一个脚本,将Docbook转换为使用Sphinx标记的reST; 它位于 GitHub
  • Christophe de Vienne编写了一个工具,用于将Open/LibreOffice文档转换为Sphinx: odt2sphinx
  • 要转换不同的标记,Pandoc 是一个非常有用的工具。

与其他系统一起使用

查看 FAQ列表中的相关部分.

先决条件

Sphinx至少需要运行 Python 3.5,以及 docutilsJinja2 库。 Sphinx应该使用docutils版本0.12或一些(未损坏的)SVN中继快照。

用法

请参阅 入门 作为介绍。它还包含本手册中针对其讨论的主题的更高级部分的链接。