Sphinx项目重复引入同一.rst文件的异常问题及解决咨询

你的问题核心是Sphinx的文件处理机制：它会标记已解析过的.rst文件，即使是在不同的only块中，只要某一次构建时先解析了其中一个项目的文档，common_text.rst就会被标记为已处理，后续切换到另一个项目构建时，Sphinx就会跳过重复解析这个文件，导致内容不显示。

给你几个可行的解决办法：

1. 用.. include::替代toctree引入公共内容 #

toctree是用来构建文档树的，会把文件标记为已处理；而include是直接将公共内容插入到当前文档中，不会留下“已处理”的标记。修改projectA.rst和projectB.rst：

different text

.. include:: common_text.rst

不管构建哪个项目，都会重新插入common_text.rst的内容，完全避开重复解析的问题，还能保持两个项目文档的独立性。

2. 动态排除非目标项目文件 #

如果坚持要用toctree，可以在conf.py里根据构建标签，动态排除另一个项目的文档，让Sphinx只处理当前项目的路径，这样common_text.rst只会被当前项目的toctree加载一次：

def setup(app):
    if 'projectA' in app.tags:
        app.config.exclude_patterns.append('projectB.rst')
    elif 'projectB' in app.tags:
        app.config.exclude_patterns.append('projectA.rst')

构建projectA时，projectB.rst会被排除，不会被解析；构建projectB时同理排除projectA.rst，从根源上避免Sphinx提前读取公共文件。

3. 把公共内容做成全局模板（适合片段式内容） #

如果common_text.rst是重复的文本片段而非完整文档结构，可以在conf.py中通过rst_prolog全局引入：

with open('common_text.rst', 'r', encoding='utf-8') as f:
    rst_prolog = f.read()

这样所有文档都会自动插入公共内容，不过这种方式适合全局通用的内容，要是需要在特定位置引入，还是用include更灵活。

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