如何用Sphinx为多文件夹Python项目生成完整文档？

1. 补全Python包结构 #

module1、module2、module3这三个子文件夹必须添加空的__init__.py文件，Sphinx只有识别到该文件才会将其视为可导入的Python包。

2. 修正docs/conf.py的核心配置 #

打开docs/conf.py，替换路径配置并确保扩展项正确：

import sys
from pathlib import Path

# 将项目根目录（包含project文件夹的目录）加入Python搜索路径
sys.path.insert(0, str(Path(__file__).parent.parent))

# 启用必要扩展
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    # 可选：添加sphinx.ext.viewcode以显示源码链接
]

# 根据你的docstring风格配置Napoleon，二选一即可
napoleon_google_docstring = True  # 适配Google风格注释
# napoleon_numpy_docstring = True  # 适配Numpy风格注释

3. 用sphinx-apidoc批量生成模块RST文件 #

进入docs目录，执行以下命令：

sphinx-apidoc -o . ../project --exclude ../project/ext_files

参数说明：

• -o .：将生成的RST文件输出到当前docs目录
• ../project：指定要扫描的根Python包
• --exclude ../project/ext_files：跳过不需要生成文档的文件夹

执行后，docs目录会自动生成project.rst、project.module1.rst等对应模块的RST文件，以及汇总用的modules.rst。

4. 配置index.rst的文档导航 #

打开docs/index.rst，在toctree区块添加生成的汇总文件或指定模块：

Welcome to Project's documentation!
===================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

如果需要更精细的结构控制，也可以直接列出单个模块：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   project.main
   project.module1
   project.module2
   project.module3

5. 构建HTML文档 #

在docs目录下执行构建命令：

• Linux/macOS环境：

make html

• Windows环境：

make.bat html

构建完成后，完整文档会生成在docs/_build/html目录，打开其中的index.html即可查看。

常见问题排查 #

• 仅生成main.py文档：检查module1/2/3是否存在__init__.py，确认sphinx-apidoc命令未遗漏这些文件夹。
• 出现导入错误：在项目根目录执行python -c "import project.module1"测试包是否可正常导入，同时核对conf.py中的路径配置是否正确。

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