如何为Django项目构建Sphinx文档

Question

我有一个Django项目，我用reST格式在代码注释里写文档，主要是为了：

1. 帮助IDE中的对话框显示信息
2. 之后用Sphinx生成HTML格式的文档

我的文档在IDE（比如PyCharm）里显示得很好，但我却无法配置Sphinx来生成HTML文档。

这是我项目的结构：

+--------------------------------------------+
|  /saassapp         # django project path   |
|     /docs          # dir for sphinx        |
|        conf.py     # sphinx config file    |
|        ...                                 |
|     settings.py    # django settings       |
|     /studyview     # django app            |
|        ...
|     ...                                    |
+--------------------------------------------+

有没有什么建议？如果能给我一个conf.py文件的例子就太好了。谢谢。

编辑

我的项目名叫saassapp，我想为一个叫studyview的模块做文档。

• Sphinx的conf.py文件：http://pastebin.com/HTYdc1rR
• Sphinx的index文件：http://pastebin.com/bu1r38TQ
• 运行make html的结果：http://pastebin.com/MWJj94EE

Answer 1

在Django 1.6中，我不能使用@MikeRyan的回答，因为from django.core.management import setup_environ这个功能已经被淘汰了。于是，我去我的conf.py文件里添加了以下内容：

import sys
import os

sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'dataentry.settings'
from django.conf import settings

让我来解释一下每一行：

1. 我使用了一个相对路径（向上两层目录），不过你也可以直接写一个绝对路径，如果你愿意的话。
2. 我的项目名称是dataentry，而settings.py文件就在这个文件夹里；你可以把名字（dataentry）改成你的项目名称。

Answer 2

把下面的内容加到你的 conf.py 文件里，这样你就不用每次都设置 DJANGO_SETTINGS_MODULE 了：

import sys, os

sys.path.append('/path/to/your/project') # The directory that contains settings.py

# Set up the Django settings/environment
from django.core.management import setup_environ
from myproject import settings

setup_environ(settings)

Answer 3

Django 1.7引入的迁移功能让之前的解决方案在新版本中无法使用了。所以你需要手动进行一些设置。就像之前的回答一样，首先要确保Django能够找到你的设置文件，然后调用django.setup()，这样就能加载设置并准备好你的模型。你需要把这些内容添加到你的Sphinx项目的conf.py文件中：

os.environ['DJANGO_SETTINGS_MODULE'] = 'projectname.settings'
import django
django.setup()