文档工具 Sphinx

本节主要介绍Python文档生成器Sphinx,在介绍一些Sphinx命令。

Sphinx简介

Sphinx 是由 Georg Brandl 开发的python文档生成器，它可以将一系列的 reStructuredText 源文件转换成各种输出格式，并且自动生成交叉引用，索引等。也支持C/C++语言，将计划支持更多的语言。

Sphinx可以生成的文档类型：HTML、htmlhelp/chm、qthelp、devhelp、LaTex、man、PDF等，而且很方便浏览和导航。

如何使用Sphinx

1. 配置工作环境:

建立工作根目录，假设命名为docs，在其中配置一个包含 conf.py 文件的工作环境，这样就可以配置Sphinx读取文件的方式以及如何建立文档。只需运行Sphinx的命令 sphinx-quickstart ，并回答运行程序提出的问题。

$ cd path/
$ mkdir docs
$ cd docs
$ sphinx-quickstart

另外，Sphinx有一个”API文档”自动生成器 sphinx apidoc.

2. 定义文件结构:

正确运行 sphinx-quickstart 之后，会配置好 conf.py 文件，同时也会生成一个 index.rst 文件（如果默认情况下），我们可以在它里面定义新的目录树结构。

刚初始化的空目录树结构是如下的代码:

.. toctree::
   :maxdepth: 2

可以在其下面列出要添加的目录结构，比如添加sphinx和reStructuredText:

.. toctree::
   :maxdepth: 2

   sphinx
   reStructuredText

关于toctree如何定义等其他内容参考 The TOC tree.

3.添加目录文件:

定义好toctree之后就要添加目录文件，也就是目录索引的内容，书写的语法规则可以学习 reStruturedText.

4.最后的组装:

到此为止，离生成最后的文档就只有一步之遥了，可以运行 sphinx-build 程序来完成组装，以生成HTML文档为例:

$ sphinx-build -b html sourcedir   builddir

其中 sourcedir 是之前创建的根目录，也就算 docs 目录， builddir 是将要存放html文档的目录，-b 选项是指选择一个编译器。

另外，sphinx-quickstare 同时还创建了 Makefile 和 make.bat 文件，还可以运行如下命令组装HTML文档:

$ make html

生成其他文档格式，比如pdf格式，可以运行 make latexpdf 调用LaTex编译器，Sphinx各种编译器可以参考 Sphinx builders <http://sphinx.pocoo.org/builders.html#module-sphinx.builders>.

参考资料

Sphinx 学习手册: http://sphinx.pocoo.org/index.html

Sphinx 下载: http://pypi.python.org/pypi/Sphinx

Read the Docs手册: http://read-the-docs.readthedocs.org/en/latest/getting_started.html