使用Sphinx的pathto(document)辅助函数为何未返回完整URL？

产生该现象的核心原因 #

pathto是Sphinx模板内置的路径生成工具，原生设计定位就是生成站点内部的相对路径，核心目的是让编译生成的静态文档不绑定具体部署环境，不管后续部署在什么域名、几级子目录下，都不需要重新编译即可正常使用。
Sphinx在构建阶段默认不会存储部署域名、协议、站点根路径这类和部署强相关的配置，因此pathto默认只会返回当前渲染页面对应目标文档的相对路径，当你在根目录的文档内调用pathto(root_doc)时，返回的就是同级的index.html，自然不包含协议、主机等URL组件。

生成绝对URL的最佳实践 #

推荐按照使用场景选择以下方案：

• 固定部署场景优先用原生配置
  如果你站点的部署地址是固定的，直接在项目的conf.py中添加配置项html_baseurl = "https://你的正式部署域名/站点根路径/"，之后在模板中调用pathto时传入第二个参数为1，即{{ pathto(document, 1) }}，就会自动拼接你配置的前缀，输出完整的绝对URL。这是Sphinx官方原生支持的方案，兼容性最好。
• 多环境部署场景用变量拼接
  如果需要适配开发、测试、生产等多个部署环境，不想在配置文件中写死域名，可以将部署域名通过环境变量或者自定义模板变量的方式传入模板，手动拼接为{{ 部署域名变量 }}{{ pathto(document) }}即可，无需修改构建逻辑即可适配不同环境。
• 复杂站点场景用扩展实现
  如果你搭建的是多语言、多版本的复杂文档站，有更复杂的路径拼接规则，可以使用适配对应场景的Sphinx第三方扩展实现绝对URL的生成。

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