什么是Sphinx？

简单来讲，就是一个基于ReStructuredText的文档生成工具。方便易用，功能强大。

而关于reStructuredText，确切的来讲是一种文档语法，类似的文档语法网上很多，像markdown、docbook等，众人熟知的应该是markdown，网上很多人基于此文档语法书写文档、博客等，它的语法相对来讲比较简单，通俗易用。markdown与reStructuredText二者算的上旗鼓相当，rst在python社区貌似用的比较多，毕竟基于rst的Sphinx是用python开发的，Python的官方文档既是采用sphinx生车的文档系统，还有最近看到的42区官方文档。

目前，Git和Bitbucket均支持rst的语法，当然我们熟知的git网站也支持md(markdown)语法，所以以后再看到以rst后缀的扩展文件，不要稀奇了。

在群里的讨论中，发现有人使用reStructuredText语法来书写自己的博客，并通过tinkerer来生成自己的博客，且看《博客迁移到tinkerer》，看上去很强大的样子。

安装

1. 安装python

  • python2.5或者python2.6都可以。
  • 如果是windows平台，推荐下载 ActivePython
  • 其他平台可以直接下载 python官方版本
  • centos平台yum安装python2.6：sudo yum install python

2. 要确认已经安装了setuptools

  • 如果已经安装，你在python安装路径下的Scripts文件夹下会找到一个easy_install.exe。
  • setuptools下载
  • centos平台yum安装setuptools：sudo yum install python-setuptools

3. 在命令行输入easy_install sphinx

  • easy_install可以自动下载并安装sphinx以及它所依赖的其他模块。
  • centos平台yum安装sphinx：easy_install sphinx

建立sphinx工程

建议使用sphinx自带的配置工具sphinx-quickstart。 – 建立一个工程目录，比如~/Note。 – 在该目录启动命令行，输入sphinx-quickstart。

会问你 n 个问题，一般来说，只需要填四个地方，其余的都直接回车就行了

  • Project name: TestNote
  • Author name(s): 煎饼
  • Project version: 1
  • Project release [1]: 1

上面加粗部分即为用户输入的部分，其他配置可以以后再配置文件中进行修改，配置完后的目录大体如下所示：

.
|-- _build
|-- conf.py
|-- index.rst
|-- make.bat
|-- Makefile
|-- _static
`-- _templates

最后在该目录中执行：sphinx-build targetDir outputDir

即可将rst文件转换为html格式的文档，然后将此文档发布到指定的Web目录下即可。