Read the Docs构建引入shields.io SVG徽章的Sphinx文档失败

本地Sphinx构建正常、Read the Docs平台构建失败的核心原因和conf.py基础配置无关：Read the Docs默认构建流程会执行严格的外链有效性校验，你引用的shields.io格式SVG徽章属于远程外链，构建环节如果遇到平台节点到shields.io的网络波动、访问拦截，就会直接中断构建流程；本地构建默认不会触发这类严格的远程资源校验，因此不会报错。

按优先级从高到低可选择以下方案：

• 方案一：本地托管徽章资源（最稳定，无网络依赖）
  将需要用到的shields.io SVG徽章提前下载到项目Sphinx配置的静态资源目录，文档内改用本地相对路径引用徽章，彻底规避构建时拉取远程资源的网络风险。
• 方案二：配置链接检查白名单
  在conf.py文件末尾添加如下配置，将shields.io域名加入链接检查忽略列表，跳过对这类徽章资源的有效性校验：

  linkcheck_ignore = [
      r"https://img\.shields\.io/.*",
      r"https://shields\.io/.*"
  ]
  

• 方案三：调整Read the Docs构建规则
  在项目根目录的.readthedocs.yaml构建配置文件中，关闭构建失败的警告触发规则，示例配置如下：

  version: 2
  sphinx:
    configuration: docs/conf.py # 替换为你项目中conf.py的实际相对路径
    fail_on_warning: false
  build:
    os: ubuntu-22.04
    tools:
      python: "3.10" # 替换为你项目实际使用的Python版本
  

你当前贴出的conf.py里存在一处配置拼写问题，建议同步修正，避免高版本依赖环境下触发额外警告：
原配置numpy_validation_checks = {all}存在两个问题：一是配置项名拼写错误，正确前缀为numpydoc_而非numpy_；二是参数格式不符合要求，正确写法为：

numpydoc_validation_checks = {"all"}

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