Sphinx构建时如何判定哪些文件需放入_source文件夹？

我想通过html_show_sourcelink和html_copy_source配置来展示文档的rst源文件，了解到这些文件会被复制到_build/html/_source目录下，但在我的项目里整个文件夹都被忽略了，导致“source”按钮无法正常工作。想知道Sphinx是依据什么规则来决定哪些文件要放进这个目录的？

核心判定规则 #

Sphinx复制源文件到_source目录的逻辑，完全围绕参与文档构建的有效源文件展开：

• 仅处理被toctree指令引用、或是作为构建入口的.rst文件（比如index.rst）。如果某个rst文件只是放在源目录下，但未被任何toctree关联，Sphinx会判定它为“未使用资源”，不会复制。
• 严格遵循conf.py里的exclude_patterns配置，只要文件/目录被加入这个列表，哪怕它被正常引用，也会被排除在复制范围外。
• 默认只识别.rst格式文件，若使用了其他格式的源文件（比如.md），需确保对应的扩展（如m2r2）已正确注册，才会被纳入复制流程。

针对你的项目的排查方向 #

结合你的情况，优先检查这几点：

1. 核对exclude_patterns配置：打开项目的conf.py，确认是否误将目标文件夹加入了排除列表，这是最常见的原因。
2. 验证文件的引用状态：确认被忽略的文件夹内的rst文件，是否都在某个toctree中被正确列出。未被引用的文件不会被Sphinx视为构建依赖。
3. 确认html_copy_source开启状态：检查conf.py里是否明确设置了html_copy_source = True——虽然默认是开启的，但如果被手动改为False，会直接导致源文件不复制。
4. 清理构建缓存重试：删除整个_build目录后重新执行sphinx-build，旧缓存可能会导致异常逻辑残留。

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