Sphinx 和可重复使用的 Django 应用程序

Question

问题

在尝试为可重复使用的 Django 应用程序生成 sphinx 文档时，我偶然发现了以下 snafoo。当 sphinx 解析 model.py 代码时，它被其中的代码试图访问 Django project 设置所阻挠。由于这是一个 standalone/reusable 应用程序 ，所以没有主要的项目提供这些设置，即没有 ROOT/PROJECT/PROJECT/settings.py 文件。

设置

为了清楚起见，这里是我所做的。遍历通常的 project 文件夹 cd ROOT/PROJECT 并创建一个 application django-admin startapp APPLICATION 产生以下结构

/ROOT/
  /PROJECT/
    /APPLICATION/ 
      admin.py
      apps.py
      models.py
      tests.py
      views.py

注意 : 没有 /ROOT/PROJECT/PROJECT/*.py 文件，因为我没有导航到 root 文件夹 cd root并像往常一样使用 django-admin createproject 创建一个项目。

下一个创建 sphinx 文档 spinx-quickstart docs 产生以下附加结构。

/ROOT/
  /PROJECT/
    /docs/
      /source/ 
        ...
        conf.py
      make.bat

即文档是在 APPLICATION 旁边构建的。

问题

在没有 settings.py 文件的情况下，我应该在 conf.py 中放置什么才能正确加载 应用程序？

作业

为了解决这个问题，我仔细阅读了许多 SO 问题、博客和 Django 文档，但没有找到简洁的解决方案。因为这个问题之前已经被问过几次所以我想鼓励它不要作为重复项关闭，如果建议的重复项中的答案使用这些片段之一作为它的解决方案。

失败 AppRegistryNotReady

from django.conf import settings
settings.configure()

类似于第一种失败方法，即发出 AppRegistryNotReady

from django.conf import settings
settings.configure()
settings.INSTALLED_APPS += ['fintech']

失败 ImproperlyConfigured
```
import django
django.setup()
```

有一个非常古老的解决方案提到了已弃用的 setup_environ

from django.core.management import setup_environ
from django.conf import settings
settings.configure()
setup_environ(settings)

这也是最喜欢的答案，但如果没有 settings.py 文件则失败。

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

我也让这个问题变得相当冗长，因为关于 SO 的相关问题相当简洁而且不是特别有用。如果有任何帮助，我正在使用 Django 1.10。

更新

从那以后我发现，如果从 setuptools 和 distutils.core 导入他们的 setup 函数，那么可以调用安装脚本来编译他们的文档，如 python setup.py build_sphinx -b BUILDER在通过 make.bat 或 Sphinx 提供的 MakeFile 在 docs/conf.py 上调用 setup.py 时，最好重新询问这个问题。

我怀疑结果会相似，即在 docs/conf.py 或 setup.py 中包含提供的答案，毕竟两者都必须在同一个 Python 会话中调用。

Answer 1

我在 Django 1.11 和 Sphinx 1.5.5 上确实遇到了同样的问题。我没能让它正常工作，你上面提到的所有解决方案也都不起作用。最后我通过将它添加到我的 Sphinx conf.py:

来解决它

import sys, os

project_path = os.path.abspath('.')
# For Django to know where to find stuff.
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_project.settings")
sys.path.append(project_path)

# For settings.py to load.
os.chdir(project_path)

# For the models to load.
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

Answer 2

如果您不想让您的文档依赖于 "demo" 项目，那么您可以在 conf.py 中手动构建设置。在路径设置部分：

import django
from django.conf import settings
import os
import sys

# add path to sys.path (this might be different in your project)
sys.path.insert(0, os.path.abspath('..'))

# pass settings into configure
settings.configure(
    INSTALLED_APPS = [
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
        'my_reusable_app',
        'any_other_dependencies',
    ]
)

# call django.setup to load installed apps and other stuff
django.setup()

# ... continue with rest of conf.py

现在 Sphinx 可以在没有项目的情况下导入应用程序模块 settings.py。其他设置可以传给settings.configure().

Answer 3

这不是问题的答案

What do I place within conf.py to properly load the application without there being a settings.py file ?

但另一种方法是：将一个最小的、可行的 Django 项目放在可重用包中。它可用于实现示例、测试（包括代码覆盖率）、开发和文档生成。我们在公司的私有存储库中就是这样做的，我在 github 上看到一些 django 包也是这样做的。

我的包的典型结构如下所示：

docs
├── conf.py
├── ... rst files
mypackage          # the actual package
mypackage_demo     # the Django project
├── .coveragerc
├── manage.py
├── settings.py
README.rst
requirements.txt
setup.py

在 docs/conf.py 中，我检查设置环境变量，如果未给出则使用演示项目：

if not os.environ.get('DJANGO_SETTINGS_MODULE'):
    os.environ['DJANGO_SETTINGS_MODULE'] = 'mypackage_demo.settings'
django.setup()

这样您就可以通过在调用 sphinx.

之前设置 DJANGO_SETTINGS_MODULE 环境变量来使用另一个项目构建文档

settings.py 仅包含运行应用程序所需的最少配置。 Django 工作的绝对最小值是这些：

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
SECRET_KEY = ''
INSTALLED_APPS = [
    'mypackage'
]

Sphinx 和可重复使用的 Django 应用程序

Sphinx and re-usable Django apps

python

django

python-sphinx

问题

设置

问题

作业

更新