如何为django项目构建sphinx文档

Question

我有一个django项目，我在docstrings中使用reST来记录以下内容：

1. 在IDE中帮助diagloags
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 ： conf.py
• Sphinx index文件： http ： //pastebin.com/bu1r38TQ
• make html结果： http ： //pastebin.com/MWJj94EE

Answer 1

Django 1.7中引入的迁移功能可以防止以前的答案适用于较新的版本。 相反，您将不得不进行手动设置。 类似于之前的所有答案，您首先必须确保Django可以找到您的设置，然后调用django.setup()来加载设置并设置模型。 将此添加到您的Sphinx项目的conf.py中 ：

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

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.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 4

我认为你必须让Sphinx了解DJANGO_SETTINGS_MODULE环境变量。 那样做

export DJANGO_SETTINGS_MODULE=mysite.settings

（或者对你来说什么是合适的价值）

然后执行

make html

在同一个终端会话中。

Answer 5

迟到但使用Django>=1.9和sphinx>=1.6.4设置相当于conf.py项目BASE_DIR的conf.py

import django
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
os.environ["DJANGO_SETTINGS_MODULE"] = "project.settings"
django.setup()

Answer 6

您实际上不需要单独的settings模块。 有时更容易（当测试和文档共享设置时）但不是必需的。

这就是dj-stripe如何为狮身人面像设置django 。 这里的关键是使用INSTALLED_APPS调用settings.configure ，因为它是唯一需要的一个设置键（如果你的应用程序当然不需要更多）：

import django
from django.conf import settings
from django.utils.encoding import force_text
from django.utils.html import strip_tags

import djstripe  # noqa


# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# sys.path.insert(0, os.path.abspath('.'))
cwd = os.getcwd()
parent = os.path.dirname(cwd)
sys.path.append(parent)


settings.configure(
    INSTALLED_APPS=[
        "django.contrib.admin",
        "django.contrib.auth",
        "django.contrib.contenttypes",
        "django.contrib.sessions",
        "django.contrib.sites",
        "jsonfield",
        "djstripe",
    ],
    SITE_ID=1,
    STRIPE_PUBLIC_KEY=os.environ.get("STRIPE_PUBLIC_KEY", ""),
    STRIPE_SECRET_KEY=os.environ.get("STRIPE_SECRET_KEY", ""),
)


django.setup()