如何为Django项目构建Sphinx文档

Question

我有一个Django项目，使用reST在docstrings中记录文档来实现以下功能：

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

- miki725

---

你运行过 sphinx-quickstart 脚本了吗？它会为你设置好 Sphinx 环境。 - mzjn

是的。我只是想不出一个合适的配置。无论我尝试什么，当我运行make html命令时，都会出现有关导入Django设置的错误... - miki725

你需要向我们展示你所得到的错误。 - mzjn

Answer 1

Django 1.7 引入的迁移功能使之前的答案在更新版本上不能正常运行。相反，您将需要进行手动设置。与之前所有答案类似，您首先需要确保Django可以找到您的设置，然后调用django.setup()加载设置并设置模型。将此添加到Sphinx项目的conf.py中：

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

- Simon

---

这个方法运作得很好，除非“automodule”指令包含例如“:undoc-members:”。在这种情况下，Sphinx从父类中提取文档并错过其中的一些内容（例如“models.FileField”）。如果删除“：undoc-members：”并适当记录类属性，则它将正常工作。 - Raffi

当我尝试执行make html时，我一直收到一个ImportError: No module named 'projectname'的错误。你知道可能是什么原因吗？ - Joabe da Luz

@JoabMendes：除非您明确将Django项目命名为“projectname”，否则您必须将其调整为您命名的项目模块。换句话说，“DJANGO_SETTING_MODULE”应该保存指向您项目设置模块的有效Python路径。 - Simon

@Simon，它保存了项目名称，我只是用它作为例子哈哈。我已经指定了DJANGO_SETTINGS_MODULE，但是我正在使用单独的设置架构。在主项目文件夹内，我有一个包含“base”、“local”和“production”设置文件的设置文件夹。本地和生产都导入基础设置。因此，我的DJANGO_SETTINGS_MODULE类似于projectname.settings.local。您认为在这种情况下我需要特定的配置吗？（我尝试过编辑sys.path）此外，我无法在conf.py中直接导入任何模块（我的目录树：http://pastebin.com/y0HqZ8pz） - Joabe da Luz

@JoabMendes 对不起，我以为那就是你收到的错误信息。只要你指定一个完整的 Django 设置文件，无论它在哪里都应该能工作。但由于你也无法导入其他模块，我建议先查看 Python 路径和/或虚拟环境设置，确保你可以在 Python REPL 中导入设置模块。 - Simon

@Simon 我采用了一种绕过方法，通过在conf.py中直接使用它们的完整路径导入每个要自动记录文档的模块（对于Python 3.4，参见：https://dev59.com/anVD5IYBdhLWcg3wKYP-?answertab=active#tab-top）。正如我所说，唯一的问题就是需要手动导入所有的模块。无论如何，感谢您的关注。(: - Joabe da Luz

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)

- Mike Ryan

---

在编程中，使用绝对路径还是相对路径更好？ - Dave

使用相对路径将使其更具可重用性。 - Mike Ryan

谢谢，sys.path.append行加入了绝对路径，让我避免了一个大麻烦。 - jooks

根据提供的目录结构，我无法看出您如何从sphinx conf文件中调用Django项目模块。 - Subhamoy S.

setup_environ 似乎已经被弃用。 - Shadi

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）更改为您的项目名称。

- Will

---

谢谢更新。我会改成接受你的答案，以保持最新状态。 - miki725

Answer 4

我认为你需要让Sphinx意识到DJANGO_SETTINGS_MODULE环境变量。因此，请执行以下操作：

export DJANGO_SETTINGS_MODULE=mysite.settings

（或者适合您的值）

然后执行

make html

在同一个终端会话中。

- mzjn

---

你可以使用subprocess模块。 - Simon Bergot

Answer 5

晚了一些，但是使用 Django>=1.9 和 sphinx>=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()

- jackotonye

Answer 6

实际上，您不需要单独的settings模块。有时候拥有一个（当测试和文档共享设置时）会更容易，但并非必需。

这是dj-stripe如何为sphinx设置django。关键在于使用settings.configure调用和INSTALLED_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()

- Janusz Skonieczny