如何为Sphinx的HTML与LaTeX构建设置不同的master_doc？

这确实是个很实用的需求——毕竟HTML和LaTeX的文档结构经常需要差异化调整，比如LaTeX可能需要更紧凑的目录或者单独的封面页。你之前尝试的两种方法各有局限，我来分享一下最稳妥的实现方式：

方法一：动态配置+独立构建目录（推荐） #

这种方法既解决了不同主文档的需求，又避免了切换构建时的全量重建问题，核心思路是：

1. 在conf.py中根据当前构建器动态切换master_doc并排除不需要的文档
2. 给不同构建器分配独立的输出目录，让它们的缓存互不干扰

步骤1：修改conf.py添加动态配置逻辑 #

在你的conf.py末尾添加以下代码：

def setup(app):
    # 监听构建器初始化事件，动态调整配置
    app.connect('builder-inited', configure_master_doc)

def configure_master_doc(app):
    builder_name = app.builder.name
    # 根据构建器类型设置主文档和排除列表
    if builder_name == 'latex':
        app.config.master_doc = 'latex_main'  # 你的LaTeX主文档文件名（不带.rst）
        # 排除HTML主文档，避免被处理
        if 'index.rst' not in app.config.exclude_patterns:
            app.config.exclude_patterns.append('index.rst')
    else:
        app.config.master_doc = 'index'  # 你的HTML主文档文件名
        # 排除LaTeX主文档
        if 'latex_main.rst' not in app.config.exclude_patterns:
            app.config.exclude_patterns.append('latex_main.rst')

步骤2：使用独立构建目录执行构建 #

默认情况下，Sphinx会把所有构建的缓存和输出放在同一个_build目录下，这就是切换构建器时触发全量重建的原因——缓存是基于配置生成的，配置变化后缓存失效。

解决方法很简单，构建时指定不同的输出目录：

# 构建HTML，输出到_build/html
make html BUILDDIR=_build/html

# 构建LaTeXPDF，输出到_build/latex
make latexpdf BUILDDIR=_build/latex

这样两个构建的缓存完全隔离，切换时不会互相影响，也就不会触发全量重建了。

方法二：多配置文件（适合复杂场景） #

如果你的HTML和LaTeX配置差异很大，除了主文档还有很多不同的设置，可以拆分配置文件：

1. 创建conf_common.py，存放所有公共配置（比如extensions、project信息等）
2. 创建conf_html.py，导入公共配置并覆盖主文档：

from conf_common import *
master_doc = 'index'
exclude_patterns = ['latex_main.rst']

3. 创建conf_latex.py，同理：

from conf_common import *
master_doc = 'latex_main'
exclude_patterns = ['index.rst']

4. 构建时指定对应的配置文件：

sphinx-build -b html -c ./_conf_html ./docs ./build/html
sphinx-build -b latexpdf -c ./_conf_latex ./docs ./build/latex

为什么之前的方法有问题？ #

• builder-inited钩子+同目录构建：同目录下缓存冲突，配置变化导致缓存失效，所以全量重建，只要分开目录就能解决
• only::指令：Sphinx的toctree在处理条件指令时，LaTeX和HTML的解析逻辑有差异，容易出现目录重复、结构混乱（比如LaTeX可能会把隐藏的toctree项也纳入目录），不如直接切换主文档来得干净

内容的提问来源于stack exchange，提问作者Clément