Add list to conf.py to skip _file_checksum()

[mosc9575]

Is your feature request related to a problem? Please describe.

Creating the docs with Sphinx 7.2.0 and later causes a ThemeError in the bokeh project. See #13548 for more details.

This is because html_css_files = [f"custom.css?v={version}"] is part of the projects conf.py and the function _file_checksum() introduced in Raise an error when local asset files contain a ? will raise the mentioned ThemeError.

I have also found the two issues #11598 and #11658 having related problems.

Describe the solution you'd like
I would suggest to add a new variable to the conf.py to skip the creation of checksum for all strings in this list.

Maybe something like:

skip_checksum = ['custom.css?']

Otherwise it would be ok to hard code the skip for the 'custom.css'.

[bryevdv]

Just noting out actual need here: We always publish the latest version of the docs to the same stable URL: https://docs.bokeh.org/en/latest/index.html If we don't add a query argument like custom.css?v={version} then repeat visitors will get an old outdated version of the CSS file after a new version is published, due to browser caching.

Another option would be to alter the filename on every build e.g. custom-{version}.css but that would add more complexity to our already very complex build, so I would prefer to avoid it. AFAIK query strings are commonly used for cache-busting in this way, and are simple to implement on our end, which is why we went that route. If there is some other simple way you can recommend to handle this, we could try it out.

[AA-Turner]

Hi @bryevdv,

The file checksum function is intended for use in cache busting too, as the checksum will change every time your CSS stylesheet changes. Sorry to have caused you/bokeh issues here.

If you’re still wanting to support Sphinx 7.0 and earlier, perhaps you could add your own custom cache busting behind a if sphinx.version_info[:2] < (7, 1) block?

If you use the version tag for something else and I’ve misunderstood, please let me know & we’ll try and fix this.

Thanks,
Adam

[bryevdv]

HI @AA-Turner we updated to 7.1 and I this in our latest dev docs so I think things are all good now

[AA-Turner]

Wonderful, thanks Bryan!

A