嵌套目录Sphinx Autodoc生成失效问题及解决方法

场景重现 #

我想用Sphinx autodoc给嵌套目录里的Python脚本生成文档，目录结构大概是这样的：

└── programs
    └── general_name
        └── another_folder
            ├── script1.py
            └── script2.py

结果生成的文档只列出了模块名称，完全看不到script1.py和script2.py里的类、函数或者注释内容，显示效果如下：

programs.general_name.another_folder package ¶
Submodules
programs.general_name.another_folder.script1 module
programs.general_name.another_folder.script2 module

项目完整目录 #

我的项目完整结构如下，供参考：

../
├── docs
│   ├── _build
│   │   ├── doctrees
│   │   │   ├── environment.pickle
│   │   │   ├── index.doctree
│   │   │   └── rst
│   │   └── html
│   │       ├── genindex.html
│   │       ├── index.html
│   │       ├── objects.inv
│   │       ├── rst
│   │       ├── search.html
│   │       ├── searchindex.js
│   │       ├── _sources
│   │       └── _static
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── rst
│   │   ├── modules.rst
│   │   ├── programs.general_name.another_folder.rst
│   │   ├── programs.general_name.rst
│   │   └── programs.rst
│   ├── _static
│   └── _templates
└── programs
    └── general_name
        └── another_folder
            ├── script1.py
            └── script2.py

我试过的操作 #

我先后执行了这两条命令，结果都没解决问题：

• docs $ sphinx-apidoc -f -o rst/ ../programs/ && make html
• $ sphinx-apidoc -f -o rst/ ../programs/general_name/another_folder/ && make html

生成的HTML里，script1和script2模块的内容还是空的。

最终解决方法 #

折腾了半天，终于发现问题出在文件夹名称里的连字符“-”！原来的文件夹名叫get_requests_from_server-10，我把它重命名为get_requests_from_server_10（把连字符换成下划线）之后，Autodoc立刻恢复正常，能正确展示脚本里的所有内容了。

为什么会这样？ #

Python的模块命名规则不允许用连字符，因为连字符会被解释成减号，导致Python无法正确导入这个模块。而Sphinx autodoc是依赖Python的模块导入机制来读取内容的，所以当目录名带连字符时，它根本没法正确识别模块，自然生成不了内容。

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