Append a?digest=hash to the end of thepydoctheme.css, computed from the file contents, so when a new CSS file is deployed, the old one is no longer used from the browser cache.

For example:

<link rel="stylesheet" type="text/css" href="_static/pydoctheme.css?digest=afc8307635b40ad4bb21df93e5fc348bcdad7f27" />

This is based on how@pradyunsg's Furo theme does it:

https://github.com/pradyunsg/furo/blob/193643fdb6787501195555244f4a9e953ef544bb/src/furo/__init__.py#L149-L161

Demo

View the source of pages athttps://python-docs-theme-previews--108.org.readthedocs.build/en/108/

Append a hash ?digest to CSS files for cache-busting

6e3e8f0

hugovk mentioned this pull request

Feb 16, 2023

Theme issue (or Firefox cache issue?)#78

Closed

pradyunsg approved these changes

Feb 16, 2023

View reviewed changes

hugovk mentioned this pull request

Feb 16, 2023

Append a hash ?digest to CSS files for cache-bustingpython/devguide#1054

Merged

hugovk merged commit6bb2816 intopython:main

Feb 25, 2023

hugovk deleted the add-hash-digest-to-css branch

February 25, 2023 09:03

hugovk mentioned this pull request

Mar 6, 2023

New release?#109

Closed

Copy link

Contributor

m-aciek commentedMar 11, 2023•
edited by hugovk
Loading

This changes break backwards compatibility with Sphinx 3.4.3 which is pinned for Python 3.10 documentation.
Following is seen in the stdout when trying to build (example):

%make html…Extension error:Handler <function _html_page_context at 0x110466020> for event 'html-page-context' threw an exception (exception: This documentation is not using `pydoctheme.css` as the stylesheet. If you have set `html_style` in your conf.py file, remove it.)

Does the same for compatibility with Sphinx 2.4.4 pinned for Python 3.9 and Python 3.8 docs:

%make html…Exception occurred:  File "/Users/maciej.olko/projects/cpython/Doc/venv/lib/python3.12/site-packages/python_docs_theme/__init__.py", line 42, in _html_page_context    raise ValueError(    ^^^^^^^^^^^^^^^^^ValueError: This documentation is not using `pydoctheme.css` as the stylesheet. If you have set `html_style` in your conf.py file, remove it.The full traceback has been saved in /var/folders/c0/vxg8dn6n28105qpdxmg3kblc0000gq/T/sphinx-err-psaoa2co.log, if you want to report the issue to the developers.Please also report this if it was a user error, so that a better error message can be provided next time.A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

(Theme seems compatible with Sphinx 2.3.1 which is used for Python 3.7.)

Would it be possible to tweak the theme to support Sphinx 3.4.3 and 2.4.4 for older Python docs?

Copy link

MemberAuthor

hugovk commentedMar 11, 2023

Thanks for reporting.

Sphinx 3.4.3:context["css_files"]=[]

Sphinx 6.1.3:context["css_files"]=['_static/pygments.css', '_static/pydoctheme.css']

Options include pinningpython-docs-theme, or ideally upgrading Sphinx for the other version branches.

But from a practical maintenance point of view, shall we just skip this for older Sphinx versions?

commit 8b88430553fdaa1d7a85296a106158b5faf99a4bAuthor: Hugo van Kemenade <hugovk@users.noreply.github.com>Date:   Sat Mar 11 13:32:42 2023 +0200    Skip cache-busting for old Sphinxdiff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.pyindex 62b16f0..bbe1352 100644--- a/python_docs_theme/__init__.py+++ b/python_docs_theme/__init__.py@@ -37,7 +37,7 @@ def _html_page_context(      assert isinstance(app.builder, StandaloneHTMLBuilder)-    if "css_files" in context:+    if sphinx.version_info >= (4,) and "css_files" in context:         if "_static/pydoctheme.css" not in context["css_files"]:             raise ValueError(                 "This documentation is not using `pydoctheme.css` as the stylesheet. "

hugovk mentioned this pull request

Mar 11, 2023

Dark theme#44

Merged

10 tasks

Copy link

Contributor

I think skipping is most pragmatic solution. 👍 I was also thinking about pinning, but the downside is it would prevent users from having another fixes from this release. When having similar conversation earlier, upgrading Sphinx wasn't told to be good option for already published stable releases, because of Linux distributions that provide Sphinx as a system package, if I recall correctly.