如何从源码目录外部使用Sphinx autodoc构建文档？

1. 调整初始配置与目录结构 #

回到项目根目录，重新梳理Sphinx的基础配置：

• 若未完成初始配置，直接执行sphinx-quickstart：选择分离源和构建目录，将源码目录设为documentation，构建目录设为build。这样生成的结构会直接匹配你的预期，无需后续移动文件。
• 若已做过之前的操作，把my_source_dir里的conf.py、index.rst移到documentation目录，删除my_source_dir内的Sphinx相关文件；同时修改根目录的Makefile，将SOURCEDIR设为documentation，BUILDDIR设为build。

2. 修正conf.py的模块路径 #

编辑documentation/conf.py，配置正确的模块查找路径，让Sphinx能识别my_source_dir里的代码：

import os
import sys
# 添加项目根目录到sys.path，确保能import my_source_dir下的模块
sys.path.insert(0, os.path.abspath('..'))

同时确认已启用autodoc扩展：

extensions = [
    'sphinx.ext.autodoc',
    # 按需添加其他扩展
]

3. 生成模块文档RST文件 #

在根目录执行命令，将my_source_dir的自动文档RST生成到documentation目录：

sphinx-apidoc -o documentation my_source_dir

执行后，documentation下会生成对应模块的RST文件（如my_source_dir.rst、modules.rst）。

4. 更新主文档索引 #

编辑documentation/index.rst，把生成的模块文档添加到目录树中，确保构建时能加载这些内容：

.. toctree::
   :maxdepth: 2
   :caption: 文档目录:

   modules  # 或直接指定my_source_dir.rst

5. 执行构建命令 #

在根目录运行构建命令：

make html

完成后，build/html会生成包含my_source_dir模块内容的完整文档，最终目录结构完全符合预期：

root
  build
    html/  # 生成的HTML文档
  documentation
    conf.py
    index.rst
    my_source_dir.rst
    modules.rst
  my_source_dir
  Makefile
  README.md

核心问题说明 #

之前构建出空文档的原因有两个：

• conf.py里的sys.path未指向项目根目录，导致Sphinx找不到my_source_dir的模块；
• index.rst未包含sphinx-apidoc生成的RST文件，构建时没有加载自动生成的模块文档。

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