如何在conf.py中访问sphinx-build -t传入的标签

报错原因 #

参考的master开发版文档和本地安装的Sphinx 5.0.2版本行为不匹配。在5.0.2版本中，tags对象不会在conf.py加载的初始阶段完成注入，直接在conf.py顶层代码调用tags.has('abc')时，tags变量值为None，因此触发属性不存在的报错。

可行解决方法 #

• 方法1：通过setup钩子访问（官方推荐兼容写法）
  Sphinx完成基础上下文初始化后，会自动调用conf.py中定义的setup函数，此时标签对象已经完成加载，可以通过app实例访问：

  # 不要在顶层直接调用tags方法，把标签判断逻辑放到setup函数内
  def setup(app):
      if app.tags.has('abc'):
          # 写入标签命中后的配置逻辑，比如条件加载扩展、切换主题配置等
          pass
  

  这种写法兼容Sphinx 4.x到最新版本，不需要额外解析参数，稳定性最高。

• 方法2：手动解析命令行参数（适用于需要顶层读取标签的场景）
  如果需要在conf.py顶层代码就判断标签值，可以直接从进程启动参数中提取-t传入的标签：

  import sys
  
  cli_tags = set()
  for i, arg in enumerate(sys.argv):
      if arg == '-t' and i + 1 < len(sys.argv):
          cli_tags.add(sys.argv[i+1])
      elif arg.startswith('-t'):
          cli_tags.add(arg[2:])
  
  # 顶层直接判断即可
  if 'abc' in cli_tags:
      # 写入标签命中后的配置逻辑
      pass
  

补充说明：升级到Sphinx 7.0及以上正式版本后，conf.py顶层直接使用tags.has()的写法即可正常运行，该版本调整了配置加载阶段的上下文注入逻辑，和开发版文档描述的行为保持一致。

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