`config-inited` event is sometimes not emitted

[choldgraf]

Describe the bug

I am trying to modify the app config if the user has not already provided a value. I'm trying to do these two things:

1. Add an extension to the extensions list if the conf.py hasn't initialized it already
2. Set a value in the config if it hasn't been specified in conf.py.

I'm trying to do this by registering a callback function attached to config-inited. However, it seems that this callback function is never being called, and so I am not sure how I'm supposed to set the config before the builder is initialized.

How to Reproduce

Here's a rough idea of code that I tried and that suggested to me the event wasn't being emitted. I added the THIS-SHOULD-BREAK at the end to try and get Sphinx to throw an error, but it never did.

def set_config_defaults(app, config):
    theme = config.html_theme_options
    
    # Navigation bar
    if "navbar_align" not in theme:
        theme["theme_navbar_align"] = "left"

    if "foo" not in config.extensions:
        extensions.append("foo")

    THIS-SHOULD-BREAK

def setup(app):
    app.connect("config-inited", set_config_defaults)

Expected behavior

set_config_defaults should modify the config, and these changes should propagate to the app build.

Your project

https://github.com/pydata/pydata-sphinx-theme

Screenshots

No response

OS

Linux

Python version

3.9

Sphinx version

5.0.1

Sphinx extensions

No response

Extra tools

No response

Additional context

For activating a new extension, I also tried app.setup_extension("extension-name"), but this then seemed to activate the extension without setting any config values (they were all None), which led to errors in the build. Activating the same extension manually in conf.py worked fine.

[tk0miya]

Could you share a reproducible example project, please? I tried to reproduce the error by pasting your code to ext.py and appending it to the extensions list. Then, I saw the following error:

$ make clean html
Removing everything under '_build'...
Running Sphinx v5.1.0+/4d7558e96
making output directory... done

Extension error (ext):
Handler <function set_config_defaults at 0x10d9a0ca0> for event 'config-inited' threw an exception (exception: name 'extensions' is not defined)
make: *** [html] Error 2

FYI:

At present, config-inited event is emitted after loading extensions from extensions variable. So changing the list on the config-inited event is meaningless. So it's better to use app.setup_extension() instead in your setup() function.

[choldgraf]

OK I dug into this a little bit more, and have some more information.

More context: I am actually trying to create a Sphinx Theme that inherits another theme, and sets some config values etc. The behavior I'm reporting here is part of that theme, not part of the conf.py build itself (sorry I forgot to mention that).

If I put the function + connect the config-inited event into the local documentation's conf.py file, then it works as expected.

However, the problem persists if I put the same code in the theme's __init__.py file in the setup(app) function. Note that the problem goes away if I switch from config-inited to builder-inited, but then changing values in app.config doesn't change the builder's context variables.

I pushed some code that is causing this problem for me (apologies for the messy theme).

• Here's the theme: https://github.com/choldgraf/jupyterhub-sphinx-theme
• Here's the __init__.py that also calls setup(app): https://github.com/choldgraf/jupyterhub-sphinx-theme/blob/main/src/jupyterhub_sphinx_theme/__init__.py#L10-L16

Note how the BREAK is in the top function.

Also, I tried calling setup_extension, but it wasn't working. You can see the attempt there with sphinx-copybutton. For some reason the variables defined in this template were returning None instead of their default values.

[choldgraf]

Ah hah - I think I figured out what is going on.

I was trying to connect a hook to the config-inited event from an HTML theme I was writing. However, I think that the theme might only be "activated" after config-inited happens. So that would explain why the theme is not able to hook into that event.

If I instead add that theme as an extension, so:

html_theme = "my_theme"
extensions = ["my_theme"]

then config-inited is correctly picked up. I bet this is what is going on.