Sphinx自定义Makefile执行make link报错：Builder name link未注册

问题描述 #

学习Sphinx教程时，已通过在links文件夹创建file.py并使用:xref:link name``语法引用链接，功能正常。但按照教程自定义Makefile添加link命令后，执行make link出现错误：

Running Sphinx v5.0.2

Sphinx error:
Builder name link not registered or available through entry point

已知教程使用旧版Sphinx Makefile，当前Makefile基于新版生成，且Makefile位于docs目录下，已调整LINKSDIR变量和链接文件导入语句，但问题未解决；Windows系统下修改make.bat也无效。

错误原因 #

新版Sphinx的Makefile默认会将未识别的目标当作Sphinx builder（通过sphinx-build -b <目标>调用），你添加的link目标被误识别为要调用名为link的Sphinx builder，但该builder并不存在，因此触发报错。

解决方案 #

1. 编写独立的自定义Makefile目标 #

在docs目录的Makefile中，添加独立的link目标，直接执行生成链接文件的逻辑，而非通过sphinx-build调用不存在的builder：

# 定义links目录路径（根据实际结构调整）
LINKSDIR := links

# 自定义link目标
link:
	@echo "Generating link files..."
	# 替换为你生成链接文件的实际命令，比如调用Python脚本
	python $(LINKSDIR)/generate_links.py

2. 适配Windows的make.bat修改 #

如果使用Windows的make.bat，需在文件中添加对应的link分支，避免触发Sphinx builder逻辑：

@echo off

rem ... 保留原bat文件的其他内容 ...

:link
echo Generating link files...
python links\generate_links.py
goto end

:end

3. 检查并移除误关联的Sphinx builder调用 #

如果之前的Makefile中，link目标错误地调用了sphinx-build -b link，需删除该逻辑，替换为上述独立执行的脚本命令。

4. 验证路径正确性 #

确认LINKSDIR变量指向的路径相对于docs目录是正确的，比如若links文件夹在docs目录下，LINKSDIR := links即可；若在上级目录，需调整为../links。

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