Sphinx生成Python项目文档时无法读取Docstrings问题求助

• 子目录缺失__init__.py文件
  Python需要对应目录下存在空的__init__.py文件才会将其识别为可导入的包，你给出的目录结构中所有MyCode下的代码子目录（如Utilities、APIs、各API子目录等）均未标注该文件，会导致autodoc无法导入模块拉取docstring。
• autodoc指令未配置成员展示参数
  默认情况下automodule、autoclass指令不会自动加载类/函数的docstring，需要在生成的rst文件中补充参数，示例如下：

  .. automodule:: APIs.API1.Class1
     :members:
     :undoc-members:
     :show-inheritance:
  

  如果你是用sphinx-apidoc生成rst，可以在执行命令时添加-e、-M参数自动生成带上述参数的配置。
• 代码目录路径配置错误
  即使你填写了相对路径，也可能因为执行编译命令的工作目录变化导致路径失效，需要在docs/source/conf.py开头固定写入绝对路径拼接逻辑：

  import os
  import sys
  sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../MyCode")))
  

  不要直接使用sys.path.append("../MyCode")这类相对路径写法。
• 模块导入失败
  你的代码如果存在运行时依赖缺失、内部导入路径错误、模块名和第三方库/标准库重名的问题，autodoc在导入模块时会失败，编译时会输出WARNING: autodoc: failed to import module xxx类警告，可优先排查编译日志的报错信息。
• NumPy格式docstring解析失败
  首先确认conf.py中开启了Napoleon的NumPy格式支持：

  napoleon_numpy_docstring = True
  

  其次检查你的docstring是否符合NumPy格式规范，格式错误会导致解析后内容为空。
• 旧编译缓存未清理
  修改配置后需要先执行make clean清空build目录的缓存内容，再执行make html重新编译，否则会沿用旧的空页面缓存。

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