如何为django项目构建sphinx文档

时间:2011-10-11 23:08:32

标签: python django documentation documentation-generation python-sphinx

我有一个django项目,我在docstrings中使用reST记录以执行以下操作:

  1. 帮助IDE中的diagloags
  2. 稍后使用Sphinx构建HTML文档
  3. 我的文档在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,我试图制作doc的模块叫做studyview。

6 个答案:

答案 0 :(得分:17)

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

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

答案 1 :(得分:14)

将以下内容添加到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)

答案 2 :(得分:12)

使用Django 1.6时,由于from django.core.management import setup_environ已被弃用,我无法使用@MikeRyan的答案。相反,我转到我的 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)更改为项目名称

答案 3 :(得分:4)

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

export DJANGO_SETTINGS_MODULE=mysite.settings

(或任何适合你的价值)

然后执行

make html

在同一终端会话中。

答案 4 :(得分:0)

迟到但使用Django>=1.9sphinx>=1.6.4设置的路径相当于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()

答案 5 :(得分:0)

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

这是how dj-stripe sets up django for sphinx。这里的关键是settings.configureINSTALLED_APPS的通话,因为它是唯一需要的设置键(如果您的应用当然不需要更多):

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()