Sphinx构建如何将主文档输出至build/html根目录？

要实现你想要的整洁项目结构，同时让构建后的index.html直接位于build/html根目录，只需要调整构建脚本的参数并确认配置文件的核心设置即可，具体步骤如下：

1. 修改构建脚本（以Makefile为例） #

打开docs目录下的Makefile，找到默认的变量定义：

SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
SOURCEDIR     = .
BUILDDIR      = build

将其修改为：

SPHINXOPTS    = -c .  # 指定conf.py所在的顶层docs/目录
SPHINXBUILD   = sphinx-build
SOURCEDIR     = src   # 把源文件目录指向docs/src/
BUILDDIR      = build

如果是Windows平台使用make.bat，对应修改为：

set SPHINXOPTS=-c .
set SPHINXBUILD=sphinx-build
set SOURCEDIR=src
set BUILDDIR=build

2. 确认conf.py的核心配置 #

确保docs/conf.py中的关键配置正确：

# 主文档文件名（对应src/index.rst，无需添加路径）
master_doc = 'index'

# 若有静态文件/额外资源，路径是相对于src目录的，比如：
# html_static_path = ['_static']
# html_extra_path = ['_extra']

3. 测试构建 #

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

make html

此时生成的index.html会直接出现在docs/build/html/根目录下，项目结构也保持了你想要的整洁状态：

docs
├─ conf.py
├─ Makefile
└─ src
   ├─ index.rst
   └─ things
      ├─ doc1.rst
      └─ doc2.rst

原理说明 #

• -c .参数告诉Sphinx从当前docs/目录读取配置文件，不用到src目录里找；
• 将SOURCEDIR设为src后，Sphinx会把src作为根源目录处理，不会在输出目录中保留src的层级结构，因此所有文档都会直接生成到build/html根目录。

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