Chu's Space

下载Sphinx，可以从Python网站上下载或是从Git下载：

wget http://pypi.python.org/packages/source/d/django-sphinx/django-sphinx-2.1.4.tar.gz
#or
sudo easy_install django-sphinx

安装完成后使用sphinx-quickstart命令进行配置：

sphinx-quickstart
Welcome to the Sphinx quickstart utility.

Enter the root path for documentation.
#项目目录，默认为当前目录
> Root path for the documentation [.]: /home/perchouli
#是否分开build文件夹和source文件夹，选择yes的话，Sphinx会建立一个source文件，把static，templates和其他配置文件放进去
> Separate source and build directories (y/N) [n]: y
#选择上面提到的static和template文件夹的前缀，默认是”_”
> Name prefix for templates and static dir [_]: :
#然后是项目名，作者名，项目版本号和项目release版本号，根据自己的项目来填写吧
> Project name: MetaDB
> Author name(s): Perchouli
> Project version: 1.0
> Project release [1.0]:

接下来的两个选项默认即可。最主要配置使用哪些Sphinx扩展。

配置完成后在项目文件夹中会多出一些文件夹和一个Makefile文件，使用make html命令可以直接生成html文档。

我们用Django提供的文档来实验一下，Django本身的文档非常优秀，利用svn可以检出文档：

svn co http://code.djangoproject.com/svn/django/tags/releases/1.2.5/docs django-docs

Django现在已经可以检出1.3版本的文档了，这里只以1.2.5做例子。进入检出的django-docs文档，直接输入make，它会列出所有可以生成的文档类型，想latepdf的话需要安装很多库，推荐使用html或是其他简单的文档：

cd django-docs
make html

执行命令后会在当前目录下生成一个_build文件夹，其中的html文件夹里就是我们需要的文档了。