Sphinx构建项目失败，报TypeError: HEAD是分离的符号引用

问题1：本地预览时版本链接指向file://协议 #

• 原因：本地构建时未配置线上文档的基础URL，版本链接默认使用本地文件路径，导致跳转异常。
• 解决步骤：
  1. 在conf.py中添加线上文档的根URL配置：

     html_baseurl = "https://<你的项目名>.readthedocs.io/"
     

  2. 若自定义了_templates/versions.html，确保链接使用完整路径：

     <a href="{{ html_baseurl }}{{ version }}/">{{ version }}</a>
     

  3. 推送到Read the Docs后，平台会自动适配正确的线上URL，本地预览的该问题属于环境差异，线上可正常工作。

问题2：Read the Docs构建时触发TypeError（HEAD为分离引用） #

• 原因：Read the Docs构建环境会从特定提交检出代码，此时Git处于分离HEAD状态，无活跃分支，而conf.py中直接调用repo.active_branch.name会触发错误。
• 解决步骤：
  修改conf.py中的版本获取逻辑，兼容分离HEAD场景：

  import git
  repo = git.Repo(search_parent_directories=True)
  try:
      current_version = repo.active_branch.name
  except TypeError:
      # 分离状态下用提交哈希前7位作为版本标识
      current_version = repo.head.object.hexsha[:7]
  

  更推荐的方式是直接使用Read the Docs提供的环境变量，无需依赖Git操作：

  import os
  current_version = os.environ.get('READTHEDOCS_VERSION', 'latest')
  

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