用sphinx写文档

1 Sphinx简介

Sphinx是一个开源的文档工具。最开始被设计用于创建新的Python文档，后来被广泛应用与Python项目，现在对C／C++的支持也已经相当不错。并且正在逐步增加对更多其他编程语言的支持。Sphinx有以下主要功能：

1，支持多种输出格式，HTML，LaTeX, ePub, Texinfo, manual pages, plain text

2，支持大量交叉引用，语法标记，函数、类，引用、术语等类似信息的自动链接；

3，支持文档层次结构，通过兄弟，父亲孩子节点间的自动链接实现轻松定义文档树形结构；

4，自动索引；

5，代码高亮处理

6，更多的扩展支持

Sphinx使用reStructuredText做为文档标记语言。很多开源项目都使用Sphinx写官方文档，在日常的工作，学习、生活中，我们不仅可以用Sphinx写项目文档，还可以利用reStructuredText所见及所得特性，以及Sphinx其他方便的功能写博客，记笔记等。

2 安装和配置

2.1 安装

Sphinx的安装可以使用源码包，esay-insall和PyPI等多种方式。

$ sudo pip install Sphinx

2.2 快速配置

Sphinx提供了一个交互式的快速配置命令sphinx-quickstart。执行sphinx-quickstart，并根据提示指定工程目录，及配制。

$ sphinx-quickstart

最后sphinx-quickstart会在指定的工程目录下自动生成y一些文件及文件夹。执行过程中，输入的配置项不同，生成的目录层次结构可能不同。但主要会有以下几个文件或文件夹。

1，build 文件夹，用于存放生成的目标我文件的目录

2，Makefile，执行make命令生成相应格式的目标文件

3，conf.py，配置文件，内容为执行shpinx-quickstart选择的配置内容

4，_static目录，所有不属于源代码的文件，如图像等都放在这个目录中

5，index.rst，文档项目的根目录，如果有其他文档文件，此文件用于自动链接组织其他文件。（注：index可在配置时指定是否使用其他名字，默认为index）

</pre><pre name="code" class="plain">.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── _static
    ├── _templates
    └── index.rst

3, 编辑文档

Sphinx使用reStructuredText作为文档标记语言，语法简单，所见即所得。如果在执行sphinx-quickstart时使用默认的index.rst做为项目根目录，则项目根目录下的index.rst将是整个项目文档的入口文件。在index.rst中根据reStructuredText语法编辑文档，最后就可以通过Makefile编译出各种格式的文档。

由于reST并没有多文档相互链接引用的机制，或者使用多个源文件编译文档。Sphinx使用用户定制的指令增加了可以将多个源文件相互链接形成最终文档的机制。toctree(Table of Content Tree) 就是这种机制的核心组成。

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   usr/index
   (many more documents listed here)

maxdepth表示最大的嵌入是层级，2表示还可以再嵌入一层父层级结构。子层级中的toctree也应当要计算在内。需要引用的源文档，直接列在toctree目录中即可，Sphinx默认使用".rst"扩展名的文档，所以不用指定后缀名。如果源文件在其他目录中，需要指定路径。

自动生成的配置文件“conf.py"是一个python源文件，如果需要更改配置，可以直接修改配置文件，而不用重新执行sphinx-quickstart。同时如果在文档中需要引用某些在配置文件中定义的变量，可以直接使用reST的引用格式引用该变量，引用后编译文档时会进行自动替换。

4，编译

Sphinx安装后支持多种格式的输出，如html，latex，epub等。检查Makefile及可知道默认支持的编译格式。但是如果想要直接编译成pdf则需要安装python rst2pdf模块，还需要修改conf.py和Makefile。或者先编译成latex格式，然后再转换成pdf格式，同样也需要pdflatex的支持。

直接执行make命令即可得到相应格式的输出：

$ make html

$ make latex

编译完成后，相应的输出文档将在_build目录下生成。

5， 总结

工作中，python相关的项目技术文档使用Sphinx完成，实际使用中给项目带来相当大的便利。生成的HTML文档可以方便的转换成confluence页面，也可以方便的生成PDF文档，省去了很多不同格式间转换的麻烦。同时reST简单的格式，可以让开发者将更多的精力放在文档正文上，而不用过多的纠结文档编排。

由于日常工作中主要接触的是英文文档，还没有尝试过用Sphinx写中文文档，听说如果需要支持中文格式，还需要额外的配置。下一篇Blog将尝试用Sphinx写，同时研究下Sphinx的中文支持。

Stay tune！

参考资料

1. Sphinx Overview： http://sphinx-doc.org/
   
2. First steps with Sphinx：http://sphinx-doc.org/tutorial.html
3. reStructuredText入门：http://sphinx-doc-zh.readthedocs.org/en/latest/rest.html
4. reStructuredText简明教程： http://jwch.sdut.edu.cn/book/rst.html
5. Quick reStructuredText : http://docutils.sourceforge.net/docs/user/rst/quickref.html