Sphinx+reStructuredText初体验

摘自：https://www.cnblogs.com/qiyeshublog/articles/2379269.html

Sphinx+reStructuredText初体验 （转载）

转自：http://blog.sina.com.cn/s/blog_583430490100x6gv.html

Sikuli docs用了Sphinx + reStructuredText来生成。
拜那3个可爱的test blocking defect所赐，今天有点时间来看看这个东东是肿么个玩法。
在网上一通乱翻之后，开始动手。
平台？Windows。。。算了。。。还是Mac和Ubuntu吧。
MacOS10.7 + Ubuntu10.04

Step 1: 安装Sphinx
推荐使用 easy_install -U Sphinx
当然啦，需要你的系统里装过easy_install才能执行。
关于easy_install，我暂时把它理解为一个类似apt-get的东东。
这一次MacOS又给了我个惊喜，居然缺省安装了，so sweet~~~
Ubuntu上安装起来也简单：
sudo apt-get install python-setuptools 就好

或者

1）http://pypi.python.org/pypi/setuptools#downloads下载setuptools-0.6c11.tar.gz包
2）解压以后进入目录，执行：sudo python setup.py install
装好以后，也是sudo easy_install -U Sphinx就好。
它会根据系统中python的版本去取不同的dependencies。
（也可以到http://pypi.python.org/pypi/Sphinx下载包包装）

Step 2：建工程
mkdir建个空目录先，cd进去
sphinx-quickstart
注意，中间木有空格木有空格
然后是一堆堆的配置提问：
> Root path for the documentation [.]:  //我们已经进过工程目录了，回车即可
> Separate source and build directories (y/N) [n]:  //要不要把source和build分开，必须y啦，不然混在一起多麻烦。
> Name prefix for templates and static dir [_]:  //问是否改生成目录的前缀，没必要啦，下划线挺好的，直接回车
> Project name:  //工程名，取个自己看着爽的吧
> Author name(s):  //同学，您金光闪闪的ID请署上
> Project version: //出于初玩，谦虚点，0.1吧。我bt，您随意。如果是给有正式版本的东东写，请严肃对待。
> Project release: //依然随便写了
> Source file suffix [.rst]: //源文件的扩展名，缺省是.rst，我需要用这个，不改
> Name of your master document (without suffix) [index]: //生成首页的名字，不用改，index多好找。
> Do you want to use the epub builder (y/N) [n]: //epub不用
...  //中间的诸多，基本上沿用缺省值就好了
> Create Makefile? (Y/n) [y]: //这个是要的，回车就好
ls一下，目录下应该有2目录2文件了： build make.bat Makefile source

Step 3: 建源文件
vi test.rst 新建一个.rst文件，按rst的格式写一些测试用内容，保存退出。

怎么写.rst请参照这个 http://docutils.sourceforge.net/docs/user/rst/quickstart.html
将该文件拷到source目录下
make html 一把
去build/html下面找生成的test.html看看
效果如何？