如何在Sphinx主题或扩展的构建事件中设置配置值？

为什么之前的写法不生效 #

Sphinx对html_theme_options的处理有独立的合并流程：配置初始化阶段会先加载所有父主题的默认选项，再逐层叠加子主题配置、用户conf.py中的自定义配置。你在setup顶层直接修改配置字典时，完整配置还未从conf.py加载完成，修改的只是临时对象，后续会被全量覆盖；在builder-inited阶段修改时，主题实例已经完成初始化，模板渲染读取的是已经拷贝到主题实例上的配置副本，仅修改app.config上的值不会同步到实际使用的配置中。

方案1：静态默认值用theme.conf配置（推荐） #

如果你的默认配置是固定值，不需要动态计算，这是Sphinx原生支持的标准方案，完全不需要写事件回调：

• 在主题包的根目录创建theme.conf文件
• 在[theme]段声明继承的父主题，在[options]段写你的默认配置即可
  示例配置：

[theme]
inherit = 你当前继承的父主题名称
stylesheet = style.css
pygments_style = default

[options]
# 在这里写所有需要设置的默认选项
option = value
sidebar_width = 300px
navigation_depth = 3

这种方式设置的默认值优先级高于父主题的默认配置，低于用户在conf.py中手动填写的html_theme_options，完全符合默认配置的逻辑，不需要额外写Python逻辑，升级Sphinx版本也不会有兼容性问题，是官方推荐的实现方式。

方案2：动态默认值用高优先级事件绑定 #

如果需要根据环境动态生成默认值，不能静态写在theme.conf里，按以下方式实现：

1. 绑定config-inited事件，将回调优先级设为低于100（数值越小执行越早，Sphinx内置的主题选项合并逻辑优先级为100，更早执行可以保证你的值不会被父主题默认值覆盖）
2. 仅在用户未显式配置对应选项时才写入默认值，避免覆盖用户自定义配置
3. 如果在更晚的事件（如builder-inited）中修改配置，需要同步修改builder上的主题配置副本
   示例代码：

def setup(app):
    def apply_default_theme_opts(app, config):
        # 定义你要设置的默认值
        default_opts = {
            "option": "value",
            "another_dynamic_opt": get_dynamic_value()
        }
        # 仅补全用户未配置的项，不覆盖用户设置
        for key, default_val in default_opts.items():
            if key not in config.html_theme_options:
                config.html_theme_options[key] = default_val

    # 优先级设为50，比Sphinx内置的主题合并逻辑更早执行
    app.connect("config-inited", apply_default_theme_opts, priority=50)

如果必须在builder-inited阶段修改配置，除了修改config.html_theme_options，还要加上一行同步配置：

app.builder.theme_options = app.config.html_theme_options

注意：不要在setup函数顶层直接修改app.config的属性，此时配置对象还未完成初始化，所有修改都会在后续加载conf.py时被覆盖。

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