godot-docs 的 ReadTheDocs 重定向管理工具：从 Git 重命名检测到 404 跳转的完整实战-平芜编程栈

文档
教程
游戏开发

【免费下载链接】godot-docs

Godot Engine official documentation

项目地址：https://gitcode.com/GitHub_Trending/go/godot-docs

导读

本文讲解 Godot 官方文档仓库（godot-docs）中一套用于维护 Read the Docs（RTD）重定向的工程化工具链。文档仓库在长期演进中会不断重命名、移动.rst源文件，导致旧链接产生 404；_tools/redirects/下的两个脚本能够自动从 Git 历史中检测文件重命名、生成 CSV 重定向清单，并批量提交到 RTD 的 API。读完本文，你将掌握这套"Git 变更 → CSV → RTD 重定向 → 前端兜底跳转"的完整链路，以及每个脚本的参数、校验规则与源码级实现原理。

一、为什么文档仓库需要重定向工具

Godot 官方文档（本项目）是一个大型 Sphinx 项目，包含上千个.rst源文件（详见 README.md 与 conf.py）。随着版本迭代，文档结构经常调整：教程被移动到新的章节目录、类参考被重新组织、旧的gdnative主题被gdextension取代。用户收藏夹、搜索引擎索引、其他网站的外链，都会指向旧路径，一旦文件被重命名就会出现 404。

RTD 本身提供了"用户自定义重定向"（user-defined redirects）功能，但官方文档对它有明确约束，本仓库在 _tools/redirects/README.md 中记录了两条关键前提：

重定向只在 404 时生效：RTD 的重定向规则仅作用于确实不存在的页面，正常存在的页面不会被劫持。
作用于全部分支与语言：重定向对所有分支（如3.4、stable、latest）和所有翻译语言统一生效。

这两条约束意味着：只要某文件在任意分支确实缺失，重定向就能安全生效；同时你无法为某个具体分支单独配置不同的跳转。README 还特别提醒：如果 RTD 将来改变这两条行为，就需要重新设计这套机制（例如加入 per-branch 逻辑）。

在 RTD 的重定向规则数量存在上限、且手动维护几千条规则极易出错的情况下，godot-docs 选择了"脚本生成 + CSV 清单 + API 批量提交 + 前端兜底"的组合方案。其中前端兜底逻辑位于 404.rst（见下文第五节）。

二、工具总览与核心文件

本仓库的_tools/redirects/目录包含四个文件：

文件	作用
convert_git_renames_to_csv.py	用 Git 检测两个版本之间被重命名的文件，输出为`source,destination`两列的 CSV
create_redirects.py	读取 CSV，通过 RTD API v3 创建/删除/校验`page`类型的重定向
requirements.txt	Python 依赖：`python-dotenv==1.2.2`、`requests==2.33.0`
README.md	使用说明文档

此外，重定向清单文件存放在仓库根目录的 _static/redirects.csv，目前已有 499 行规则（截至本仓库快照），例如：

source,destination /about/index.html,/index.html /community/tutorials/gdnative/index.html,/tutorials/plugins/gdnative/index.html /development/compiling/compiling_with_mono.html,/engine_details/development/compiling/compiling_with_dotnet.html /development/consoles/consoles.html,https://godotengine.org/consoles/

注意两点：路径统一以/开头并以.html结尾（对应 Sphinx 构建后的产物路径）；目标地址既可以是站内相对路径，也可以是外部https://链接。

从源码结构看，两个脚本的分工非常清晰：convert_git_renames_to_csv.py只负责"发现"重命名并产出待办清单（数据准备阶段），create_redirects.py负责"执行"——它既可以做安全的干跑（--dry-run），也可以真正调用 RTD API 落库，还会在写入前对清单做去重与格式校验。

三、环境准备（Setup）

按照 README.md 的说明，使用前需要完成三步准备：

安装依赖：
```
pip3 install -r requirements.txt
```
依赖锁定在 _tools/redirects/requirements.txt：requests用于调用 RTD API，python-dotenv用于从.env文件读取认证令牌。
确保 Git 可用：convert_git_renames_to_csv.py依赖git命令，要求 Git 存在于PATH中。在 convert_git_renames_to_csv.py 的源码里，脚本启动时会先执行git --version做前置检查，失败则直接输出 "Git not found. It's required to run this program." 并退出。
配置 API 令牌：与 RTD API 交互需要有效密钥，通过环境变量RTD_AUTH_TOKEN提供；也可以放在.env文件中由python-dotenv自动加载（此时需要保证 dotenv 包已安装）。create_redirects.py 的load_auth()会先尝试dotenv.load_dotenv()，再读取os.environ.get("RTD_AUTH_TOKEN", "")，取不到合法令牌就打印 "Missing auth token..." 并中止。

从源码看，认证信息最终在 create_redirects.py 中被组装为请求头：{"Authorization": f"token {RTD_AUTH_TOKEN}", "User-Agent": USER_AGENT}，即 RTD API v3 的标准 Token 认证方式。

四、标准工作流：从 Git 重命名到 RTD 重定向

README 给出了一套完整的操作流程。以下以"3.4分支相对于stable分支重命名了一批文件，需要为它们创建重定向"为例。

第一步：生成重命名清单

python convert_git_renames_to_csv.py stable 3.4

命令接受两个位置参数：revision1（旧分支/版本）和revision2（新分支/版本），并输出重定向候选列表。源码 convert_git_renames_to_csv.py 还额外提供-f/--output-file选项，指定输出文件路径；不指定时结果打印到标准输出。

第二步：追加到重定向清单文件

python convert_git_renames_to_csv.py stable 3.4 >> ../../_tools/redirects.csv

将生成的 CSV 追加到仓库的 _static/redirects.csv（注意 README 中的路径../../_tools/redirects.csv是相对于_tools/redirects/目录而言，实际文件位于仓库根目录的_static/redirects.csv）。README 明确提醒：追加后务必人工 double-check 清单内容。

第三步：批量提交到 ReadTheDocs

python create_redirects.py

脚本读取 CSV 中的全部规则，查询 RTD 上已存在的重定向，跳过重复项，然后逐个通过 API 创建。README 特别说明："The script takes care to not add duplicate redirects if the same ones already exist."——即脚本不会重复添加已存在的同一条重定向。

底层原理：convert_git_renames_to_csv.py 如何检测重命名

这个脚本的核心思路是直接利用 Git 的差异检测能力，关键代码如下：

前置校验：断言两个 revision 不同（"Revisions must be different."），且不能包含/（"Revisions must be local branches only."，即只支持本地分支）；随后用git rev-list HEAD..<revision>确认两个分支都存在于本地仓库。
执行 Git diff：
```
git diff --find-renames --name-status --diff-filter=R <revision1> <revision2>
```
其中--find-renames启用重命名检测，--diff-filter=R只保留标记为 Rename 的文件。
过滤.rst文档：只保留小写以.rst结尾的文件（f.lower().endswith(".rst")），排除图片等二进制资源。
转换为重定向路径：对每个重命名条目，从git diff输出的R100\told\tnew格式中拆分出源与目标路径，把.rst后缀替换为.html（因为 RTD 上用户访问的是构建产物），并确保路径以/开头。
排序输出：按源路径排序后写入 CSV，表头为source,destination。

若两个分支间没有任何.rst重命名，脚本会输出 "No renames found for ... -> ..." 并提前返回。

底层原理：create_redirects.py 如何提交与去重

create_redirects.py 的工作流程可以概括为"加载 → 校验 → 对比 → 提交"四步：

加载 CSV：默认读取../../_static/redirects.csv（可通过-f/--file覆盖），并校验文件头必须是source,destination两列，见源码 L255-L285。
读取 RTD 现有重定向：调用get_paginated()分页拉取https://readthedocs.org/api/v3/projects/godot/redirects/（单页 1024 条），只处理type == "page"的条目，其余类型跳过并打印提示。API 返回 401 时提示检查RTD_AUTH_TOKEN。
逐条校验：每条规则必须满足——源地址以/开头且以.html或/结尾；目标地址以/或https://开头且同样具备合法后缀；源不能等于目标（"redirects to itself!"）；同一个源地址不能冲突映射到多个目标（collision 检测）；完全重复的条目会被静默跳过。相关校验函数见 is_valid_source_url。
提交：对不在现有清单中的规则，用HTTP.post向 RTD 发送{"from_url", "to_url", "type": "page"}JSON 请求；HTTP 201 表示成功创建，429（限流）时按retry*retry秒退避重试至多 5 次，其他错误码则报错退出。每次请求之间通过time.sleep(API_SLEEP_TIME)（0.2 秒）限速，避免触发 RTD 的速率限制。
网络健壮性：脚本用requests的Retry（status_forcelist=[429,500,502,503,504]、backoff_factor=2、最多 3 次）包装 HTTPAdapter，对 GET/POST/DELETE 等请求自动重试。

常见命令行选项

选项	含义
`-f/--file <path>`	指定 CSV 清单路径（默认`_static/redirects.csv`）
`--dry-run`	干跑模式：只输出将要创建的重定向信息，不调用任何 RTD API
`--dump`	只导出（或配合`--delete`删除）RTD 上现有的重定向，跳过提交
`--delete`	删除 RTD 上所有`page`与`exact`类型的现有重定向
`--validate`	校验每个目标页面确实存在（隐含`--dry-run`），目标为`https://`外部链接时跳过
`-v/--verbose`	开启详细输出

--validate的实现在 validate()：它把目标路径拼接在../../_build/html前缀下，用os.path.exists检查本地构建产物是否存在，不存在的目标会打印 "Invalid destination" 警告。因此该功能依赖本地已用 Sphinx 构建过文档（_build/html目录）。

五、前端兜底：404 页面中的 JavaScript 重定向

一个值得注意的实现细节是：RTD 能配置的重定向数量有上限，而本项目迁移过的页面远超该上限。为此，仓库在 404.rst 的 404 页面中内置了一段 JavaScript 兜底逻辑：

页面加载后，根据当前 URL 推导基础路径（如/en/latest），fetch该路径下的_static/redirects.csv；
逐行解析 CSV，若当前访问路径以某条规则的source结尾，则用window.location.replace()跳转到对应destination（https://开头的目标直接跳转外部，站内路径则拼上基础路径）；
该机制只作用于"确实无效的页面"（即 404 页面），与 RTD 重定向"仅 404 时生效"的语义一致。

也就是说，本项目的重定向体系是双层的：RTD 服务端重定向覆盖常见路径（由create_redirects.py管理），404 页面的前端 JS作为服务端规则数超限时的补充。这也是为什么 _static/redirects.csv 必须随文档一起发布到站点静态资源目录的原因。

另外，conf.py 中启用了notfound.extension（Sphinx Notfound 插件），并在本地开发时通过notfound_urls_prefix = ''去掉/en/latest前缀，方便本地起服务直接测试/404.html的兜底跳转逻辑。

六、实践要点与注意事项

分支顺序不能反：README 与脚本 docstring 都强调，convert_git_renames_to_csv.py的第一个参数是旧分支（如stable），第二个是更新分支（如master/latest），顺序反了生成的映射方向就会颠倒。该规则同样在 create_redirects.py 的文档字符串中有明确说明。
只管理page类型：create_redirects.py明确只增删page类型的重定向，其他类型（如exact、prefix等）可以继续在 RTD 网站上手动维护；但反过来，所有page重定向都必须通过这套工具管理，否则脚本在写入时会直接覆盖其他渠道的改动（README 对此有专门警告）。
提交前务必人工复核：README 建议在追加 CSV 后 double-check，因为 Git 的重命名检测基于相似度阈值，偶尔会误判或漏判。
路径规范：源/目标必须是/开头的站点相对路径（或https://外部目标），后缀限定为.html或/；指向锚点的目标（如...html#section）也支持，校验时会剥离#后的锚点再判断后缀。
重复与冲突防护：脚本从"RTD 现有规则"和"本次清单内部"两个维度去重，同时拦截"同一源地址映射多个目标"的冲突，保证清单可安全重复执行。

七、结语

这套_tools/redirects/工具链是 godot-docs 仓库"工程化维护文档可用性"的一个缩影：用git diff --find-renames自动发现内容迁移，用标准化 CSV 沉淀可审计的重定向清单，用 RTD API 批量落库，再用 404 页面 JS 做超限兜底。对于任何长期演进的大型 Sphinx 文档项目，这套"数据生成 + 清单管理 + API 执行 + 前端兜底"的四层模式都有直接的借鉴价值。