Sphinx生成Django文档 – Perchouli 的技术文章和其他文章Blog

Perface

前几天Jeff在公司分享了PyCon2011的视频，其中有介绍到Django的Document，解释了不同的Document（API/FAQ/REFER）应该对应不同级别用户的问题，以及自动生成Document的一些工具。今年年会的Tutorial似乎有不少涉及Document的，比如Documenting Your Project With Sphinx。所以本文跟风一下，介绍用Sphinx生成Django文档的入门技巧。

Install

下载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

Configure

安装完成后使用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文件夹里就是我们需要的文档了。

附上生成的HTML文件，内容、样式都和官方文档完全一样，但是可以离线观看，方便网络不好的同学：

文件信息：Django-doc.zip 大小：2.9MB

链接检查：2011年3月19日