在构建过程中更新 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 以查看是否有任何通过命令行提供的覆盖值。

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

避免使用 config-inited 事件

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