编译 django doc 遇到的问题(生成本地django 文档)

下载django项目的包里有个docs文件夹，就是这个了，里面是text格式，要转成html格式，需要用到一个工具：

sphinx，安装sphinx一般是用setuptools的easy_install工具(D:\Python25\Scripts\easy_install.exe)，执行easy_install.exe sphinx就可以安装成功了。


要安装setuptools的话，下载源码包解压后，可以看到里面有个setup.py，执行python setup.py install，就行了。


安装完sphinx后会有这个工具：D:\Python25\Scripts\sphinx-build.exe（linux：是在/usr/local/bin/sphinx-build），再执行sphinx-build G:\Soft\Django-1.2.1\docs G:\Help\Python\Django\docs 就行了。

这里的G:\Soft\Django-1.2.1\docs 是源路径(txt格式的地方)，G:\Help\Python\Django\docs 是编译后的目标路径（html格式）。


编译django doc遇到的两问题，一个是路径编码问题，开始的时候G:\Soft\Django-1.2.1\docs是这样的：G:\Soft \项目\Django-1.2.1\docs ,这里有“项目”两个汉字，结果在执行sphinx-build 的时候 D:\Python26\Lib\ntpath.py 里面的一行代码就会报错了：

Exception occurred:
  File "D:\Python26\lib\ntpath.py", line 112, in join
    path += "\\" + b
UnicodeDecodeError: 'ascii' codec can't decode byte 0xb1 in position 8: ordinal not in range(128)

很鄙视这样的问题，搞死人。



还有更低级的错误：

Exception occurred:
  File "G:\Soft\Django-1.2.1\docs\_ext\djangodocs.py", line 215, in parse_django_adminopt_node
    from sphinx.directives.desc import option_desc_re
ImportError: No module named desc

说没有des模块，靠，又搞了很久。

后来是在http://svn.python.org/projects/doctools/trunk/sphinx/directives/desc.py   这上面找到这个文件，然后放在 D:\Python25\Lib\site-packages\Sphinx-1.0.4-py2.6.egg\sphinx\directives 。



这个估计是在用easy_install安装Sphinx时候的问题，easy_install下载的地方没有这个文件。



如果没什么问题的话，会有如下的输出：

C:\Users\<用户名>>

D:\Python25\Scripts\sphinx-build.exe G:\Soft\Django-1.2.1\docs G:\Help\Python\django\doc
Running Sphinx v1.0.4
loading pickled environment... not yet created
No builder selected, using default: html
building [html]: targets for 187 source files that are out of date
updating environment: 187 added, 0 changed, 0 removed
reading sources... [  0%] contents
reading sources... [  1%] faq/admin
reading sources... [  1%] faq/contributing
reading sources... [  2%] faq/general
reading sources... [  2%] faq/help
reading sources... [  3%] faq/index
reading sources... [  3%] faq/install
reading sources... [  4%] faq/models



再找个chm工具生成chm，方便查看。