👌 Add warning log for config values that cannot be cached (#12203)

As a user and/or extension developer, it can be a source of confusion when,
on performing a `sphinx-build` for a cached project, 
an unchanged configuration variable is always marked as changed (triggering a full rebuild).

This is often due to the variable being an unpicklable value,
which is silently omitted from the cache (i.e. the `environment.pickle`).

This commit introduces a specific warning for when a configuration variable is omitted from the cache,
allowing users to understand the root of the problem.
This commit is contained in:
Chris Sewell
2024-03-27 12:59:24 +01:00
committed by GitHub
parent 448cb9931d
commit 430866e029
2 changed files with 27 additions and 0 deletions

View File

@@ -70,3 +70,19 @@ def test_texinfo_warnings(app, warning):
app.build(force_all=True)
warnings_exp = TEXINFO_WARNINGS.format(root=re.escape(app.srcdir.as_posix()))
_check_warnings(warnings_exp, warning.getvalue())
def test_uncacheable_config_warning(make_app, tmp_path):
"""Test than an unpickleable config value raises a warning."""
tmp_path.joinpath('conf.py').write_text("""
my_config = lambda: None
show_warning_types = True
def setup(app):
app.add_config_value('my_config', None, 'env')
""", encoding='utf-8')
tmp_path.joinpath('index.rst').write_text('Test\n====\n', encoding='utf-8')
app = make_app(srcdir=tmp_path)
app.build()
assert strip_colors(app.warning.getvalue()).strip() == (
"WARNING: cannot cache unpickable configuration value: 'my_config' [config.cache]"
)