+++++++++++++++++++++++++++++++++++++++++
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 <http://docutils.sourceforge.net/rst.html>`_ 。 如果你是浏览的是网页版本的笔记，可以在侧边栏点击Show Source链接查看这个文档的 `reStructuredText`_ 源码。

这里有一个非常简明的 `reStructuredText 入门文档 <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ 这个简明教程里面的内容完全够我们使用了。看完学会用，估计不过一两个小时时间吧。

如果小组里面有同学可以贡献时间翻译一下最好不过了,也可以去看看  `reStructuredText快速参考 <http://wiki.venj.me/restructuredtext-quick-reference>`_ 。

Sphinx当然不仅仅是 `reStructuredText`_ 他还有一些自己的特性，比如在文档中加入代码。具体到用到的时候去 http://sphinx.pocoo.org/ 查就可以了。

我们目前需要知道的就是sphinx的toctreeb的概念。toctree是用于组织各个rst文件之间的关系的。
你在index.rst里面可以看到一个toctree。我用了glob参数，然后写上 setout/\*它就会自动把setout里面的东西都包含进来了。

在这里对想想文档里提交自己的内容的同学提个要求： 每个文件不要太长。主要是为了方便他人的修改。

参考资料
==================

完整的入门教程：

http://sphinx.pocoo.org/tutorial.html

http://sphinx.pocoo.org/

Google

学新技术永远不要忘了google