如何配置环境以自定义修改Sphinx Alabaster主题的Jinja模板

两个核心错误导致配置失效、主题找不到：

• 路径不匹配：你创建的_themes目录在site根目录，而conf.py存放在site/source/目录下，html_theme_path填写的相对路径是相对于conf.py所在目录的，Sphinx无法定位到你复制的alabaster2主题
• 继承逻辑异常：本地复制的主题会优先从自定义主题路径查找继承的basic主题，而Sphinx内置的basic主题不在你的_themes目录下，导致主题加载失败，后续的html_theme_options自然全部不生效

1. 修正路径配置 #

二选一即可：

• 方案A：将site/_themes文件夹整体移动到site/source/目录下，保留conf.py里的html_theme_path = ["_themes"]配置不变
• 方案B：不移动现有目录，直接修改conf.py中的配置为html_theme_path = ["../_themes"]

2. 修复主题继承配置 #

打开你复制的_themes/alabaster2/theme.conf文件，确认首行继承配置指向Sphinx内置的basic主题（如果已经是该配置则不用修改）：

[theme]
inherit = basic
# 其余原有stylesheet、sidebars等配置全部保留

3. 重新编译 #

修改完成后先执行make clean清理旧的编译缓存，再执行make html即可正常加载配置和自定义主题。

不需要全量复制整个Alabaster主题代码到本地，用Sphinx内置的模板重载机制更便于后续维护：

1. 在site/source/目录下创建_templates文件夹
2. conf.py中保留官方Alabaster主题配置即可，不需要自定义主题路径：

html_theme = 'alabaster'
templates_path = ['_templates']
# 原有全部html_theme_options配置保留不变

3. 你需要修改哪个Alabaster的Jinja模板，就把对应名称的模板文件从虚拟环境的Alabaster安装目录复制到_templates文件夹下修改即可，Sphinx编译时会优先加载该目录下的同名模板，覆盖官方主题的默认逻辑。

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