为 Django 项目生成文档时，Sphinx 失败答案

【问题标题】：Sphinx fails when generating documentation for Django project为 Django 项目生成文档时，Sphinx 失败
【发布时间】：2017-01-25 13:43:15
【问题描述】：

我正在尝试使用带有 autodoc 和 napoleon 扩展名的 Sphinx 为我的 Django 项目自动生成文档。

使用sphinx-quickstart，我创建了以下结构：

MyDjangoProject
├── __init__.py
├── config
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── docs
│   ├── Makefile
│   ├── build
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst
├── myfirstapp
│   ├── __init__.py
│   ├── models.py
│   └── views.py
├── mysecondapp
│   ├── __init__.py
│   ├── models.py
│   └── views.py

...

我已自定义 docs/source/conf.py 以反映我的项目结构。

import os
import sys

proj_folder = os.path.realpath(
    os.path.join(os.path.dirname(__file__), '../..'))

sys.path.append(proj_folder)

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')

import django
django.setup()

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode']

# The rest of the default configuration...

然后我转到项目的根目录并运行sphinx-apidoc -f -o docs/source .。这会将每个模块的.rst 文件添加到docs/source。

最后我转到MyDjangoProject 并运行make html。这会失败，每个模块都会出现错误提示

Traceback (most recent call last):
  File "/Users/Oskar/git/MyDjangoProject/venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 551, in import_object
    __import__(self.modname)
ImportError: No module named MyDjangoProject.myfirstapp

我做错了什么？

【问题讨论】：

标签： django python-sphinx documentation-generation autodoc sphinx-napoleon

【解决方案1】：

由于您已将MyDjangoProject 添加到python 路径，因此您应该将myfirstapp 导入为myfirstapp 而不是MyDjangoProject.myfirstapp。

【讨论】：