Sphinx-multiversion构建文档时出现下载文件不可读报错

问题根源 #

sphinx-multiversion构建多版本文档时，会把Git仓库里的源码复制到临时目录再处理，但默认只复制Git已追踪且没被忽略的文件。如果你的examples.zip没被Git加入追踪，或者_downloads目录被.gitignore排除了，临时目录里就不会有这个文件，自然会报找不到的警告。

解决办法 #

1. 让Git追踪这个zip文件（最稳妥） #

• 执行命令把文件加入Git：

  git add docs/source/_downloads/examples/examples.zip
  git commit -m "添加示例下载包"
  

• 要是.gitignore里有排除_downloads的规则，得删掉或者改一下，确保文件能被Git追踪到。

2. 配置sphinx-multiversion强制包含目标目录 #

要是不想把zip文件加入Git，就在docs/source/conf.py里加个配置，指定要包含的路径：

# 在conf.py里添加这部分配置
smv_include_patterns = [
    "_downloads/**",  # 包含_downloads下所有文件和子目录
    "*.rst",          # 保留默认的rst文件规则
    "_static/**",     # 有静态文件的话也加上
]

注意：这个配置只对Git已追踪的文件生效，如果文件完全没在Git里，还是得用第一种方法。

3. 检查下载链接的路径 #

确认RST里的链接路径没错：

• 如果是相对当前RST文件的路径，去掉开头的斜杠：

  :download:`here <_downloads/examples/examples.zip>`
  

• 要是用的是相对于source根目录的绝对路径，保留斜杠也可以，但前提是文件已经被复制到临时目录的对应位置。

4. 重新构建测试 #

再跑一遍构建命令：

sphinx-multiversion "docs/source" "docs/build/html" -W --keep-going -n

这时候临时目录里应该就有那个zip文件了，警告也会消失。

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