Sphinx 文档工具
原文地址：http://start-up-python.readthedocs.org/en/latest/setout/sphinx.html#sphinx
转载此文作为一个记录
Sphinx是python的文档工具，也非常适合用于记笔记，所以我们这次学习选择python-sphinx就无可厚非了。 下面我简单介绍一下这个工具，希望大家能在最短的时间内学会使用这个工具。
首先安装sphinx
ubuntu:
$sudo apt-get install python-sphinx
arch:
$sudo pacman -S python-sphinx
或者:
$easy_install sphinx
然后终端中进到docs目录里，运行下面命令试试:
$make html
然后你会在docs/_build/html目录里看到生成的html版本的文档。
如何写Sphinx文档
Sphinx文档使用的是标记语言 reStructuredText 。 如果你是浏览的是网页版本的笔记，可以在侧边栏点击Show Source链接查看这个文档的 reStructuredText 源码。
这里有一个非常简明的 reStructuredText 入门文档 这个简明教程里面的内容完全够我们使用了。看完学会用，估计不过一两个小时时间吧。
如果小组里面有同学可以贡献时间翻译一下最好不过了,也可以去看看 reStructuredText快速参考 。
Sphinx当然不仅仅是 reStructuredText 他还有一些自己的特性，比如在文档中加入代码。具体到用到的时候去 http://sphinx.pocoo.org/ 查就可以了。
我们目前需要知道的就是sphinx的toctreeb的概念。toctree是用于组织各个rst文件之间的关系的。 你在index.rst里面可以看到一个toctree。我用了glob参数，然后写上 setout/*它就会自动把setout里面的东西都包含进来了。
在这里对想想文档里提交自己的内容的同学提个要求： 每个文件不要太长。主要是为了方便他人的修改。