Activate Jinja2's debug extension

[Mischback]

Problem

For theme development it is not strictly required but would be nice to determine, what is placed in the rendering context.

Jinja2 >= 3.0.0 does provide the jinja2.ext.debug extension, which does provide a {% debug %} tag for this purpose.

However, that Jinja2 extension is not activated by Sphinx (which is good and expected).

Possible Solution A

The extension might be activated by calling add_extension("jinja2.ext.debug") on the Jinja Environment object (Reference).

Tracking this object down is not as simple as expected, but probably it can be achieved this way:

# in file conf.py

def activate_jinja2_debug_ext(app):
    """Activate Jinja2 debug extension.

    Prototype of this function is based on 
    https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events

    FIXME: If this works, make sure to add documentation, using the references
           from the research. Quite a ride through ``sphinx`` source code!
    """
    app.builder.templates.environment.add_extension("jinja2.ext.debug")

def setup(app):
    # Connect a custom handler to the ``builder-inited`` event.
    #
    # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
    app.connect("builder-inited", activate_jinja2_debug_ext)

# sphinx.application
# ``_init_builder()`` suggests, there is an attribute ``builder`` on the ``app`` object
# see ``create_builder()``, which calls ``sphinx.registry.create_builder()``;
# both of these functions return a ``Builder`` instance

# sphinx.builders (in ``create_template_bridge()``)
Builder.templates = BuiltinTemplateLoader() 

# sphinx.jinja2glue
BuiltinTemplateLoader.environment = SandboxedEnvironment()  # this is from jinja2.sandbox