-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Warning "cannot cache unpickable configuration value" when config contains a reference to a function #12300
Comments
Heya, this is not a bug, it is intended: #12203 If you are happy to live with not having caching, then you simply add the config: (note also the new config to show warning types: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-show_warning_types |
With 959f73f, |
I'd note that one of the reasons I added this is that I literally come across the issue when adding this configuration: https://myst-nb.readthedocs.io/en/latest/authoring/custom-formats.html#custom-formats, I feel this may be the better route for extensions to go, rather than relying on Sphinx to have complex cache special cases |
@chrisjsewell thanks for the quick response. I have been trying to make sense of this for a bit now. I do understand why the warning is shown in the sense of what triggers the warning. What I do not understand are the consequences that the warning is warning me about. I thought that issue with unintended full rebuilds was resolved with 959f73f
While I do agree that this is a better way, I want to state that I am not a fan of using a Python file as a configuration file and then imposing limitations like these. Simply because that behaviour is then very unexpected for the average user, in my opinion. Most people won't know about caching environments and configurations and so on. But I understand that this is not a simple problem, and this may still be the best solution. My reaction to this warning was "it fails my CI, I don't really know what it wants to tell me and I don't know how to silence it". With my current and still somewhat limited overview, I'd argue that this warning should be improved to better guide the user. Even when explicitly searching for it, I have a hard time finding information in the documentation about the process of pickling and caching environments and the benefits and consequences this has. I think this would underline my point that many users won't know about this. |
Not that is not the case: for configuration variables that are set with sphinx/sphinx/environment/__init__.py Lines 326 to 330 in da4c6a7
So for these configuration variables, if they do not get cached, then they will for sure trigger a "full" rebuild, i.e. re-parsing all documents and re-writing all output files (e.g. HTML files) As per #12203, I certainly feel it is not a good user-experience, to have these re-builds triggered, without any indication that it is because of un-cacheable variables for configuration variables, that are set with sphinx/sphinx/builders/html/__init__.py Lines 141 to 143 in da4c6a7
If this hash is not equal, then it will trigger a "write" re-build, i.e. just re-writing all the HTML files here, then yes there is now some "handling" of these un-cacheable values I honestly feel that it is not ideal, that there are these two wildly different mechanisms for cache-busting 🤔
Well, this is why I introduced #12131, and in the future would like to make it the default 😄, |
From the description of #12203 :
Agreed about this, it can be confusing! However, in sphinx-gallery we ensure that the If it doesn't cause a rebuild in practice, maybe one improvement would be to make the message more verbose in saying that this inability to cache properly will cause a rebuild only if the object does not have a stable And maybe at the SG end we can figure out how to make the objects pass the EDIT: Also I noticed that the |
I'd just re-emphasise: this only works (and has only ever worked) with config variables marked as This is the case for sphinx-gallery, but obviously not the case for others: https://github.com/sphinx-gallery/sphinx-gallery/blob/e22fc20463055199dee565db3c21c34c9d195c6e/sphinx_gallery/gen_gallery.py#L1550-L1552 |
Closing this now:
A |
Thanks for mentioning about the caching discrepancy with |
canonical#203 introduced a function into the `html_context` configuration. In parallel, a Sphinx update added a warning message for such cases (see sphinx-doc/sphinx#12300). This commit suppresses the new warning for now. We might be able to find a better solution later. Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
I get the same warning/error, but my sphinx_gallery_conf only contains strings contrary to what sphinx says:
|
Pretty sure it's the same error because sphinx-gallery fills in entries in the conf when it loads, and some of those entries are classes |
oh, we must wait #1289 then, got it |
Describe the bug
When the configuration contains a reference to a function, the warning "cannot cache unpickable configuration value" is show. If warnings are treated as errors, this of course fails the configuration build.
This problem was introduced in v7.3.0. It seems to only occur on a clean build (at least in the case that I observed). This is still problematic because CI workflows commonly do clean builds and then fail.
For the reason why function references are used in the configuration, I'll refer to #11777 where there is a more detailed explanation of the reasons.
The steps for reproduction are the same as in that issue, albeit with a different outcome/error.
How to Reproduce
Add the following content to the end of the default
conf.py
in thesource
directory:Run
make html
and notice "WARNING: cannot cache unpickable configuration value: 'sphinx_gallery_conf'" in the output.This problem only occurs on a clean build (at least in this case), so it is necessary to run
make clean
before reproducing the problem again.Environment Information
Sphinx extensions
Additional context
The text was updated successfully, but these errors were encountered: