GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Append a hash ?digest to CSS files for cache-busting by hugovk · Pull Request #108 · python/python-docs-theme

Conversation

@hugovk

@hugovk hugovk commented Feb 16, 2023 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

Fix #78.

Append a ?digest=hash to the end of the pydoctheme.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 at https://python-docs-theme-previews--108.org.readthedocs.build/en/108/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

m-aciek reacted with rocket emoji
All reactions
  • 🚀 1 reaction
@hugovk
Append a hash ?digest to CSS files for cache-busting
6e3e8f0
@hugovk hugovk mentioned this pull request Feb 16, 2023
Theme issue (or Firefox cache issue?) #78
Closed
pradyunsg
pradyunsg approved these changes Feb 16, 2023
View reviewed changes
@hugovk hugovk mentioned this pull request Feb 16, 2023
Append a hash ?digest to CSS files for cache-busting python/devguide#1054
Merged
@hugovk
hugovk merged commit 6bb2816 into python:main Feb 25, 2023
@hugovk
hugovk deleted the add-hash-digest-to-css branch February 25, 2023 09:03
@hugovk hugovk mentioned this pull request Mar 6, 2023
New release? #109
Closed
@m-aciek

m-aciek commented Mar 11, 2023 •
edited by hugovk
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

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?

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk

hugovk commented Mar 11, 2023

Copy link
Copy Markdown
Member Author

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 pinning python-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 8b88430553fdaa1d7a85296a106158b5faf99a4b
Author: Hugo van Kemenade <[email protected]>
Date:   Sat Mar 11 13:32:42 2023 +0200

    Skip cache-busting for old Sphinx

diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py
index 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. "
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk hugovk mentioned this pull request Mar 11, 2023
Dark theme #44
Merged
10 tasks done
@m-aciek

m-aciek commented Mar 11, 2023

Copy link
Copy Markdown
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.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk hugovk mentioned this pull request Mar 11, 2023
Skip cache-busting for old Sphinx #113
Merged
@hugovk

hugovk commented Mar 11, 2023

Copy link
Copy Markdown
Member Author

Please see PR #113.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@hugovk hugovk mentioned this pull request Mar 13, 2023
[3.10] gh-101100: Fix Sphinx warnings in turtle module (GH-102340) python/cpython#102638
Merged
@m-aciek m-aciek mentioned this pull request Jul 26, 2023
Theme broken with Sphinx 7.1.0 #136
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pradyunsg pradyunsg pradyunsg approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Theme issue (or Firefox cache issue?)

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@hugovk @m-aciek @pradyunsg
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.