Sphinx未提取函数Docstrings问题求助

我之前也碰到过一模一样的问题，折腾了好一阵才找到症结，给你列几个最可能的排查方向，一步步来试：

1. 先把conf.py的核心配置核对一遍 #

这是最容易踩坑的地方：

• 确保extensions里确实包含sphinx.ext.autodoc，别拼错单词：

  extensions = [
      'sphinx.ext.autodoc',
      # 其他你用到的扩展...
  ]
  

• 一定要给Sphinx加上项目根目录的路径！不然它找不到你的代码文件，自然提取不了Docstrings。如果你的项目根在../（和source文件夹同级），就在conf.py开头加上：

  import os
  import sys
  sys.path.insert(0, os.path.abspath('../'))
  

  路径要对应你的实际项目结构，别写错层级。

2. 确认RST文件的指令是否正确 #

你提到用了.. automodule::，得确保细节没出错：

• 模块路径要准确！比如你的send_confirm_msg方法在my_project.notifier模块的某个类里，那指令得写对：

  .. automodule:: my_project.notifier
     :members:
     :undoc-members:  # 可选，用来显示没有写Docstrings的成员
  

• 如果你是想单独提取某个类的方法，也可以直接针对类写指令，这样更精准：

  .. autoclass:: my_project.notifier.NotifyClass
     :members: send_confirm_msg
  

  注意:members:后面的冒号不能丢，拼写也别错成member。

3. 检查Docstrings格式和编码 #

你的Docstrings用了俄文和reStructuredText风格的标签（:param:这类），Sphinx默认支持reStructuredText格式，而且对UTF-8编码的支持也很好，但可以做个小测试：把Docstrings换成英文试试，排除编码相关的隐性问题。另外如果之前配置过sphinx.ext.napoleon扩展（用来支持Google/NumPy风格Docstrings），也要确认有没有冲突，但你这种格式应该没问题。

4. 清空缓存重新生成 #

有时候旧的生成文件或缓存会干扰新的结果，按这个顺序操作：

1. 删除source目录下之前用sphinx-apidoc生成的所有RST文件
2. 重新生成apidoc文件：

   sphinx-apidoc -f -o source/ ../
   

3. 清理旧的build缓存，再重新编译：

   make clean
   make html
   

5. 升级Sphinx版本试试 #

如果以上都没用，可能是版本兼容问题。旧版本的Sphinx对某些Docstrings场景支持不好，升级到最新版试试：

pip install --upgrade sphinx

我当时就是因为sys.path没加对，导致Sphinx找不到我的模块，折腾了半天。你先从核对sys.path和RST的模块路径开始，这两个是最常见的坑。

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