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

Question

我正在尝试使用 Sphinx with the autodoc and napoleon 扩展自动为我的 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

我做错了什么？

Answer 1

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

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

Sphinx fails when generating documentation for Django project

django

documentation-generation

python-sphinx

autodoc

sphinx-napoleon