使用Sphinx为多个文件夹生成文档

Question

我目前正在做一个Python项目，它的规模比预期的要大。
我的代码是用文档字符串记录的，现在我想用Sphinx生成一个全面的文档。
然而，无论我如何尝试，我都无法找到一种方法在一个命令中生成所有内容。

这是更新后的我的项目结构:

.
├── docs
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
├── project
│   ├── module1
│   │   ├── file1.py
│   │   └── file2.py
│   ├── ext_files
│   │   └── >files we dont care about
│   ├── module2
│   │   ├── file3.py
│   │   ├── file4.py
│   │   └── file5.py
│   ├── module3
│   │   ├── file6.py
│   │   ├── file7.py
│   │   ├── file8.py
│   │   └── file9.py
│   └── main.py
├── README.md
└── requirements.txt

理想情况下，我希望HTML文档遵循这种结构。

我试过了:

• sphinx-quickstart，给出适当的信息
• 然后编辑conf.py文件，添加sphinx.ext.autodoc,sphinx.ext.napoleon以及sys.path.abspath(..)(缩短)
• 使用sphinx-apidoc在我的3个不同的文件夹在许多不同的方式
• 在我的主文档目录
的子目录中移动.rst文件
• 修改index.rst和/或modules.rst，并添加我的文件夹/文件的名称

我还尝试手动添加automodule指令，以及创建子模块。
我试过设置sphinx-autogen来自动发现我的不同模块。
但是，无论我做什么，它要么只生成main.py文件的文档，要么什么都不生成。

请帮帮我，我快疯了。无论我遵循什么教程或阅读什么文档，我似乎都找不到答案。
提前感谢!

Answer 1

在尝试了几乎所有方法之后，我解决了这个问题:

1. 更新我的项目结构以反映上面的一个(灵感来自Lex Li给出的链接)
2. 删除我所有的sphinx文件，重新运行sphinx-quickstart，确保将构建和源代码分开
3. 确保project的每个子文件夹都有一个__init__.py文件
从docs/source文件夹，编辑我的conf.py文件，并添加

import os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', 'project'))
sys.path.insert(0, basedir)

5. 新增sphinx.ext.autodoc和sphinx.ext.napoleon扩展名
6. 在index.rst
的toctree指令下添加modules从docs文件夹中，运行sphinx-apidoc -o ./source ../project -f --separate
7. 然后，从docs/开始，运行make html。

运行sphinx-apidoc后，确保为每个模块生成一个<module>.rst文件。

我觉得这个详细的答案可能对某些人有用，因为它是多个StackOverflow答案的汇编。

请注意我的项目目录是这样的:

.
├── docs
│   ├── build
│   └── source
├── project
│   ├── module1
│   ├── module2
│   ├── module3
└── └── module4
└── tests