构建Sphinx文档时未定义DJANGO_SETTING_MODULE

Question

我遵循本教程为我的Django项目生成文档。

我已将sys.path.append(os.path.join(os.path.dirname(__name__), '..'))添加到文档目录中的conf.py文件中。

但是运行make html总是给我这样的错误：

配置不正确：请求设置LOGGING_CONFIG，但未配置设置。在访问设置之前，必须定义环境变量DJANGO_SETTING_MODULE或调用SETTINGS.config（）。

我的项目运行良好，所以我不确定应该在哪里调用settings.configure()？

Answer 1

目录结构

基于以下目录结构的普通安装，以下是应该工作的步骤。只要conf.py中的路径设置正确，目录结构就可以不同。

├── docs
│   ├── Makefile
│   ├── build
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst
└── myproj
    ├── anapp
    │   ├── __init__.py
    │   ├── admin.py
    │   ├── apps.py
    │   ├── migrations
    │   │   └── __init__.py
    │   ├── models.py
    │   ├── tests.py
    │   └── views.py
    ├── manage.py
    └── myproj
        ├── __init__.py
        ├── settings.py
        ├── urls.py
        └── wsgi.py

狮身人面像配置

conf.py需要一些设置，以便autodoc能够引导Django应用程序：

# 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.join(os.path.abspath('.'), '../../myproj'))    # <•• 1
os.environ['DJANGO_SETTINGS_MODULE'] = 'myproj.settings'                  # <•• 2
import django
django.setup()                                                            # <•• 3

1⇒将Django项目目录（带有manage.py的目录）附加到Python路径，这对于2和解析.rst文件中的autodoc指令是必要的。

2⇒使用设置模块的位置设置env变量。这个例子是基于一个普通的django管理设置。如果您使用的是更复杂的设置结构（例如，从一些基本设置扩展而来的dev、staging、production设置），则只需更新路径，例如myproj.settings.dev。

3⇒最后调用django.setup()是填充Django的应用程序注册表所必需的，Sphinx需要该注册表才能从完整的Django设置中生成文档。

现在一切都应该就绪，以便$ make html与autodoc协同工作。