时间戳

首页 > 解决方案 > 无法在我的 Django 项目中使用 Sphinx 生成自动文档

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

问题描述

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

.. automodule:: account.models
    :members:

让我告诉你我做了什么。

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

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

我在 sphinxconfg.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 模块以在应用程序中启用多种语言，我不确定它如何影响文档生成，但是，为了修复这个错误，我在 sphinxconf.py文件中添加了以下几行：

from django.conf import settings
settings.configure()
  1. 现在，如果我运行make html命令，我会收到以下消息：

“翻译基础架构无法在” AppRegistryNotReady 之前初始化：在应用注册表准备好之前，翻译基础架构无法初始化。检查您在导入时没有进行非惰性 gettext 调用。

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

import django
django.setup()
  1. 但是现在，我在运行make html命令时收到以下消息：

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

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

我该如何解决？

太感谢了。

重要链接：

我的项目设置：settings.py

狮身人面像文件夹：文档/

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

from django.conf import settings
settings.configure()

import django
django.setup()

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

标签： pythondjangopython-sphinx

解决方案

你需要告诉 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

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

推荐阅读