Sphinx autosummary递归选项无法完全遍历子文件夹问题咨询

这是autosummary的典型默认行为 #

autosummary的:recursive:选项仅对Python包/模块生效。如果你的data文件夹及其子文件夹不是Python包（即缺少__init__.py文件），Sphinx不会将它们识别为可递归的包结构，自然不会遍历子文件夹内的内容。而src能正常遍历，是因为里面的.py文件属于独立Python模块，符合autosummary的处理范围。

实现完整遍历的解决方案 #

分两种场景处理：

场景1：子文件夹包含Python代码（需提取文档字符串） #

• 给data下的所有子文件夹（fans、functions、systems）添加__init__.py文件（空文件即可），将它们转为Python包。
• 在docs/source/conf.py中，把项目根目录添加到Python路径，确保Sphinx能找到这些包：

  import os
  import sys
  sys.path.insert(0, os.path.abspath('../..'))  # 路径根据你的docs目录层级调整
  

• 重新执行make html，autosummary就会递归遍历所有子包及其模块的文档字符串。

场景2：子文件夹是数据文件/非Python代码 #

autosummary本身只处理Python模块的文档字符串，这类非代码目录无法通过autosummary自动遍历。如果要展示目录结构，需要手动编写reStructuredText内容，或者自定义脚本生成目录结构的文档片段嵌入到汇总页面中。

内容的提问来源于stack exchange，提问作者Élio Pereira