Python Tech

Sphinx生成Django文档

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日

0 0 投票数
文章评分
订阅评论
提醒
guest

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据

1 评论
最新
最旧 最多投票
内联反馈
查看所有评论
python.cn(news, jobs)

已推荐到:http://simple-is-better.com/news/379