如何使Sphinx文档适配GitHub Pages？能否在docs根目录设置指向build的链接？

当然可以！你想通过在/docs根目录放置跳转文件或符号链接指向/docs/build/index.html的思路完全可行，完美适配你当前的目录结构。下面给你两种具体实现方式，再补充些优化配置让整个流程更丝滑：

方法1：HTML跳转文件（最稳妥） #

这种方法兼容性拉满，完全不用担心跨环境或托管服务的兼容性问题，所有静态站点平台都能识别。直接在/docs目录下新建index.html，写入以下内容：

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="refresh" content="0; url=./build/index.html">
</head>
<body>
    <p>如果未自动跳转，请点击 <a href="./build/index.html">这里</a> 访问文档。</p>
</body>
</html>

提交这个文件到仓库后，GitHub Pages加载/docs/index.html时会自动跳转到build目录下的文档首页。

方法2：符号链接（更简洁） #

如果你偏爱更简洁的方式，符号链接也是可行的，GitHub Pages本身支持符号链接：

• Linux/macOS：进入/docs目录，执行命令：

  ln -s build/index.html index.html
  

• Windows（管理员PowerShell）：

  New-Item -ItemType SymbolicLink -Path .\index.html -Target .\build\index.html
  

⚠️ 注意：如果团队里有Windows成员，需要确保他们的Git开启了符号链接支持，执行git config core.symlinks true后再提交符号链接，避免出现文件异常。

额外优化：统一Sphinx配置 #

为了让文档生成流程更顺畅，建议调整Sphinx的配置文件和Makefile：

1. 修改docs/source/conf.py，指定输出目录并确保能导入src目录的代码（如果需要生成API文档的话）：

import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))

# 固定HTML输出目录到../build
html_output_dir = '../build'

2. 调整docs/Makefile里的BUILDDIR变量：

BUILDDIR      = build

这样每次执行make html时，生成的文档都会直接输出到/docs/build，不用手动调整路径。

最后验证一下：本地执行make html生成文档，把docs目录下所有内容（包括新的跳转文件/符号链接、build、source、Makefile）提交到GitHub，GitHub Pages就能正常加载你的文档啦！

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