【新手入门】如何生成本地的Django的参考文档

有的时候，不能上网，需要在本地查看Django的参考文档。但在Django包中提供的是txt格式的，查看起来很不方便。可以使用Sphinx来生成HTML格式的参考文档。

说明：因为我没有安装setuptools和Sphinx，所以这里的步骤是从安装这两个工具开始。

安装环境和版本
操作系统：Windows XP
Python版本：2.6
setuptools版本：0.6c9
Django版本：1.0.2-final
Sphinx版本：0.6.1

具体的安装步骤

第一步，先安装setuptools  http://pypi.python.org/pypi/setuptools/0.6c9

 

下载源码包
http://pypi.python.org/packages/source/s/setuptools/setuptools-0.6c9.tar.gz#md5=3864c01d9c719c8924c455714492295e

解压缩后，通过在命令行进入解压手的目录，执行：
python setup.py install

第二步：安装Sphinx，在命令行执行：
easy_install -U Sphinx

第三步：生成Django参考文档。
在命令行执行：
sphinx-build C:\Django\docs C:\Django-docs

其中C:\Django\docs是Django压缩包，解压后的docs目录。
C:\Django-docs是生成的参考文档的目录（如果不存在，需要先创建）

如果你看到命令行上有
Running Sphinx v0.6.1
No builder selected, using default: html
...
的输出，表示已经开始创建HTML格式的参考文档了。

如果，你看到的是
Extension error:
Could not import extension djangodocs (exception: No module named htmlwriter)
之类错误的信息，说明你用的Django和Sphinx的版本不兼容。 造成的原因主要是Django的docs/_ext/djangodocs.py和docs/_templates/layout.html中使用了Sphinx0.6以前版本的接口。

解决方法：
根据http://code.djangoproject.com/attachment/ticket/10539/10539-sphinx06-compatibility.diff

中的对比修改djangogocs.py和layout.html两个文件。

或者直接下载附件，覆盖旧的文件（先备份原来的两个文件）。

 

评论

2 楼 iwinux 2009-06-23  

我遇到的情形跟你相似，不过解决步骤上稍有不同，详情请看这里：https://groups.google.com/group/python-cn/browse_thread/thread/ad834cd21a1a75d6

1 楼 wangchao719 2009-06-06  

果然有不兼容的问题，谢谢lz详细的解释。
那个easy_install感觉和apt-get有点像。