海报网

可能是国内最大的 Django 应用网站 ...

↑我也要推荐

Sphinx 生成 Django 文档

发布时间:2011-06-17 02:03:31, 关注:+5335, 赞美:+6, 不爽:+5

本文标签: 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日

# 作者微博:http://weibo.com/perchouli

如果你觉得本站对你有帮助,欢迎向本站赞助 :P

使用支付宝捐赠

Copyright© Python4cn(news, jobs) simple-is-better.com, 技术驱动:powered by web.py 空间主机:Webfaction

版权申明:文章转载已注明出处,如有疑问请来信咨询。本站为 python 语言推广公益网站,与 python 官方没有任何关系。

联系/投搞/留言: en.simple.is.better@gmail.com 向本站捐赠