Sphinx为Cookiecutter模板执行make latexpdf时出现LaTeX编译错误

LaTeX的hyperref包解析\sphinxhref的URL参数时，会先处理掉转义符，你写的\{\{会被还原为未转义的{{，大括号在LaTeX中是分组控制符号，URL里的未转义{会被识别为新分组的起始标记，后续的}就会被判定为多余的闭合符号，因此触发Extra }报错。HTML生成流程无此限制，所以展示完全正常。

• 方案一：在Sphinx配置中自动处理URL编码
  在项目的conf.py文件中添加如下代码，会在构建LaTeX版本时自动将URL中的大括号替换为标准URL编码，无需修改原有文档内容：

  def escape_latex_href(app, node, post):
      if app.builder.name == 'latex' and node.get('refuri'):
          node['refuri'] = node['refuri'].replace('{', '%7B').replace('}', '%7D')
  
  def setup(app):
      app.connect('doctree-resolved', escape_latex_href)
  

• 方案二：手动替换链接中的大括号为URL编码
  直接修改reST文档里的链接定义，把{{替换为%7B%7B，}}替换为%7D%7D，示例如下：
  原定义：

  .. _Python setup configuration: {{cookiecutter.project_slug}}/setup.py
  

  修改后：

  .. _Python setup configuration: %7B%7Bcookiecutter.project_slug%7D%7D/setup.py
  

  该方案无需修改配置，且编码后的大括号在HTML和PDF中都可以被正常识别，不影响链接跳转。

• 方案三：条件编译隐藏PDF版的链接
  如果不需要在PDF中保留这些相对链接的可点击属性，可以用Sphinx的条件编译指令，仅在HTML版本保留链接，LaTeX版本显示纯文本：

  .. only:: html
  
      `Python setup configuration`_
  
  .. only:: latex
  
      *Python setup configuration*
  

内容的提问来源于stack exchange，提问作者Bjorn van de Sand