Skip to content

♻️ Serve static assets via html_static_path#276

Merged
chrisjsewell merged 1 commit into
mainfrom
static-assets-rework
Jul 12, 2026
Merged

♻️ Serve static assets via html_static_path#276
chrisjsewell merged 1 commit into
mainfrom
static-assets-rework

Conversation

@chrisjsewell

@chrisjsewell chrisjsewell commented Jul 12, 2026

Copy link
Copy Markdown
Member

This replaces the hand-rolled static-asset handling (update_css_js + update_css_links) with Sphinx's standard html_static_path mechanism, registered once on builder-inited and gated to HTML-format builders.

Changes

  • CSS/JS moved (git mv, contents unchanged) from sphinx_design/compiled/ to a dedicated sphinx_design/static/ dir, served under the same output names (sphinx-design.min.css, design-tabs.js) — HTML output is byte-identical to main
  • Non-HTML builders no longer gain a spurious _sphinx_design_static directory in the output, and nothing is written into outdir outside Sphinx's own copying, which also removes the mkdir crash on Sphinx ≥8.1/Windows
  • Sphinx floor raised to >=7.2: native ?v= cache-busting replaces the old md5-in-filename scheme, and the test-suite sphinx_path compat branch is dropped
  • The private sphinx_design._compat.findall shim is removed; all call sites now use node.findall(...) directly
  • epub behaviour is unchanged (Epub3Builder.format == "html", so it keeps receiving the assets, as before)

Verification

  • New tests/test_assets.py: the latex test was confirmed failing against the previous implementation (reproducing the spurious static dir); the html test asserts _static assets exist and are linked with ?v= checksums; plus an epub smoke test
  • Full suite passes locally on Sphinx 7.2.6 / 7.4.7 / 8.2.3 / 9.0.4 / 9.1.0 (docutils 0.20–0.22); builder-by-builder output audit (html/dirhtml/singlehtml/epub/json/latex/text/man/texinfo/gettext) matches main for HTML-family builders and is clean for the rest
  • Wheel/sdist inspected: the only difference from main is the two renamed asset paths; icon data stays in sphinx_design/compiled/

Closes #200
Closes #235
Supersedes #241

Replace the hand-rolled update_css_js/update_css_links handlers with a
single builder-inited hook that appends sphinx_design/static/ to
html_static_path, letting Sphinx copy, checksum and cache-bust the CSS/JS
itself. Non-HTML builders no longer gain a spurious _sphinx_design_static
directory in their output (#200, #235).

Bump the Sphinx floor to >=7.2 (native CSS checksums since 7.1) and replace
the docutils findall compat shim with direct node.findall calls.
@chrisjsewell chrisjsewell force-pushed the static-assets-rework branch from 79e1e5f to 7a3f261 Compare July 12, 2026 17:00
@codecov

codecov Bot commented Jul 12, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.33%. Comparing base (9f62c7d) to head (7a3f261).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #276      +/-   ##
==========================================
+ Coverage   90.08%   90.33%   +0.25%     
==========================================
  Files          12       12              
  Lines        1119     1086      -33     
==========================================
- Hits         1008      981      -27     
+ Misses        111      105       -6     
Flag Coverage Δ
pytests 90.33% <100.00%> (+0.25%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@chrisjsewell chrisjsewell merged commit 1bfd79d into main Jul 12, 2026
25 checks passed
@chrisjsewell chrisjsewell deleted the static-assets-rework branch July 12, 2026 17:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing build directory leads to builder-inited error _sphinx_design_static directory in _build/latex

1 participant