无法在我的 Django 项目中使用 Sphinx 生成自动文档

Question

我正在使用 sphinx 将文档添加到我的 Django 项目（github link，该项目是开源的），但是当我尝试生成 python 文件的自动文档时遇到了很多错误。我包含了一个带有文档字符串的 models.py 文件，但是当运行make html 时，我遇到了不同的错误。我做了一些更改并且错误正在发生变化，但我不确定我是在修复它们还是只生成一个新错误。如果删除包含的 models.py 文件，一切运行良好。换句话说，只有当我在 .rst 文件中包含以下行时才会生成该错误：

.. automodule:: account.models
    :members:

让我告诉你我做了什么。

1. 当我运行make html 命令时，我的第一个错误如下：

警告：autodoc：导入模块 u'account.models' 失败；这 引发了以下异常： 没有名为 account.models 的模块

我在 sphinx confg.py 文件中添加了以下几行：

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

我创建了一个名为docs 的文件夹来包含sphinx-quickstart 命令生成的所有文件，因此，abspath 的值为../../。

1. 好的，现在，当我运行make html 命令时，我得到了第二个错误：

ImproperlyConfigured：请求设置 USE_I18N，但设置不正确 配置。您必须定义环境变量 DJANGO_SETTINGS_MODULE 或在访问前调用 settings.configure() 设置。

我已经集成了国际化 Django 模块以在应用程序中启用多种语言，我不确定它如何影响文档生成，但是，为了修复这个错误，我在 sphinx conf.py 中添加了以下几行文件：

from django.conf import settings
settings.configure()

1. 现在，如果我运行 make html 命令，我会收到以下消息：

"翻译基础设施不能在 " AppRegistryNotReady：翻译基础设施不能 在应用程序注册表准备好之前初始化。检查你没有 在导入时进行非惰性 gettext 调用。

为了“修复它”（我不确定它是否真的修复了它），我在 sphinx conf.py 文件中有以下几行：

import django
django.setup()

4. 但是现在，当我运行 make html 命令时收到以下消息：

RuntimeError：模型类 django.contrib.contenttypes.models.ContentType 没有声明 显式 app_label 并且不在 INSTALLED_APPS 中的应用程序中。

现在我找不到修复它的选项。如果我从我的 .rst 文件中删除包含 .py 文件，则所有文件都可以完美运行，但我需要包含在我的所有 python 文件中创建的文档字符串。

我该如何解决？

非常感谢。

重要链接：

我的项目设置：settings.py

Sphinx 文件夹：docs/

注意：我已在本地将以下几行添加到 conf.py 文件中：

from django.conf import settings
settings.configure()

import django
django.setup()

这些更改在 github 存储库中不可见。

Answer 1

您需要告诉 Django 使用哪些设置。在docs/conf.py 试试这个：

import os
import sys

# I've simplified this a little to use append instead of insert.
sys.path.append(os.path.abspath('../../'))

# Specify settings module
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'app.settings')

# Setup Django
import django
django.setup()

# ... leave the rest of conf.py unchanged

这应该允许构建的其余部分正确运行。