如何在Sphinx的Jinja模板中访问默认build目录外的文件？

问题分析 #

你用pathto()函数尝试访问其他build目录的文件时失败，核心原因是：pathto()是Sphinx专门用于生成当前构建项目内部文档的路径函数，它只会解析当前build对应的source目录下的rst文件所生成的HTML路径，无法识别其他build目录里的外部文件路径。

解决方案 #

1. 直接使用原生相对路径

跳过pathto()，直接写跨build的相对路径字符串即可，因为跨build的文件属于当前文档的外部资源，不需要Sphinx内部路径解析：

<a href="../adminbuild/contents.html" class="btn btn-primary show-white">Bla Bla Bla</a>

注意：路径需要根据当前HTML文件的实际位置调整。比如如果用户build目录下的HTML生成在build/html/子目录，那么访问adminbuild的路径应该是../../adminbuild/contents.html（因为build/html/上两级才是和adminbuild同级的根目录）。

2. 在conf.py中定义全局路径变量

如果需要统一管理跨build的路径，可在source/conf.py中添加全局上下文变量，方便模板复用和后续修改：

# source/conf.py
html_context = {
    'admin_contents_url': '../adminbuild/contents.html',
    'dev_contents_url': '../devbuild/contents.html'
}

然后在Jinja模板中直接调用变量：

<a href="{{ admin_contents_url }}" class="btn btn-primary show-white">Bla Bla Bla</a>

3. 保证build目录结构一致性

确保所有build目录的HTML输出结构一致，比如都直接生成在build目录根下，或者都在html子目录里，避免因构建结构差异导致相对路径出错。

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