Sphinx生成Django文档时显示基础视图而非自定义views.py视图

这种情况我碰到过好几次，大概率是Sphinx没正确加载你的Django项目环境，或者模块路径配置错了，下面一步步排查：

1. 检查Sphinx配置文件（conf.py）的路径和Django环境设置 #

这是最常见的问题，Sphinx必须能找到你的Django项目并加载配置，否则会默认解析Django自带的模块。

打开docs/source/conf.py，做这两个修改：

• 把你的Django项目根目录添加到sys.path，比如你的项目结构是my_project/，里面包含my_app/和my_project/settings.py，那添加：

  import os
  import sys
  # 根据你的实际路径调整，确保能找到你的app模块
  sys.path.insert(0, os.path.abspath('../../'))
  

• 初始化Django环境，让Sphinx能识别你的自定义模块：

  import django
  # 替换成你的项目settings模块路径
  os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'my_project.settings')
  django.setup()
  

2. 确认rst文档里的autodoc指令指向正确模块 #

别不小心把模块写成django.views了！要指向你自己的应用的views模块。比如你的app叫my_app，那在你的rst文件里应该写：

.. automodule:: my_app.views
   :members:
   :undoc-members:
   :show-inheritance:

:members:会抓取所有带注释的函数/类，:undoc-members:会包含没写文档字符串的，根据需要调整。

3. 清除Sphinx缓存后重新生成 #

有时候旧的缓存文件会搞事情，先删掉_build文件夹，再重新生成文档：

# 进入docs目录
cd docs
rm -rf _build/
# 重新生成HTML文档
sphinx-build -b html source/ build/

4. 检查函数注释格式（可选） #

虽然你的getFirstFolder已经有文档字符串，但确保注释格式是Sphinx能识别的，比如reStructuredText风格：

def getFirstFolder(req):
    """返回指定目录的第一个文件夹路径
    
    :param req: 请求对象
    :type req: django.http.HttpRequest
    :return: 文件夹路径字符串
    :rtype: str
    """
    # 函数逻辑...

如果用Google风格的注释，记得在conf.py里添加sphinx.ext.napoleon扩展来支持。

5. 排查命名冲突（少见但可能） #

如果你的视图函数名和Django基础视图重名了（比如你也写了个View类），Sphinx可能会优先识别Django的，不过看你的代码里是getFirstFolder，应该不会有这个问题，但还是确认下。

按照上面的步骤走一遍，基本就能解决显示错视图的问题了。

内容的提问来源于stack exchange，提问作者Anthony Petrillo