在构建期间更新 Sphinx 配置

有时你希望在构建期间更新配置值。例如，如果你想在用户没有提供值的情况下设置默认值，或者如果你想将值从一个关键字移动到另一个关键字以进行弃用。

以下是一些在 Sphinx 中以“正确”方式执行此操作的技巧。

更新配置：使用 app.config

例如，app.config.foo = "bar"。出于某种原因，当 Sphinx 设置东西时，它直接使用 __dict__，但这似乎与这里描述的模式没有区别。

更新主题选项：使用 app.builder.theme_options

例如，app.builder.theme_options["logo"] = {"text": "Foo"}。

检查用户是否提供了默认值：app.config._raw_config

app.config._raw_config 属性包含所有**用户提供的**值。如果要检查是否有人手动指定了某些内容，请使用此属性。例如，如果用户没有提供该选项，则 "somekey" in app.config._raw_config 将为 False。

您也可以检查 app.config.overrides 以获取任何通过 CLI 提供的覆盖。

我们将这两个检查捆绑在一个名为 _config_provided_by_user 的辅助函数中。

避免使用 config-inited 事件

此主题在触发 config-inited 之后激活，因此，如果您在此主题中编写一个依赖于它的事件，那么它将永远不会发生。您可以使用的最早事件是 builder-inited。