♻️ Serve static assets via html_static_path (#276)

Replace the hand-rolled static-asset copying (update_css_js/update_css_links)
with Sphinx's standard html_static_path mechanism, gated to HTML-format
builders. Assets move to sphinx_design/static/ with output names unchanged;
non-HTML builds no longer gain a spurious _sphinx_design_static directory,
and nothing is written into outdir outside Sphinx's own copying. The Sphinx
floor moves to >=7.2 (native ?v= cache-busting) and the private
_compat.findall shim is removed.

Closes #200
Closes #235

Author: chrisjsewell

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
       entry: npm run css
       require_serial: true
       pass_filenames: false
-      # args: [--style=compressed, --no-source-map, style/index.scss, sphinx_design/compiled/style.min.css]
+      # args: [--style=compressed, --no-source-map, style/index.scss, sphinx_design/static/sphinx-design.min.css]
 
     - id: tsc
       name: tsc (jsdoc)

AGENTS.md

@@ -294,7 +294,7 @@ The extension uses SASS for styling:
 
 1. SASS source files are in `style/`
 2. Compiled using `npm run css` (requires Node.js)
-3. Output goes to `sphinx_design/compiled/style.min.css`
+3. Output goes to `sphinx_design/static/sphinx-design.min.css`
 4. CSS is automatically copied to build output during Sphinx builds
 
 ## Key Files
@@ -339,7 +339,7 @@ The extension uses SASS for styling:
 
 1. Edit SASS files in `style/`
 2. Run `npm run css` to compile (or `pre-commit run --all css`)
-3. Compiled output goes to `sphinx_design/compiled/style.min.css`
+3. Compiled output goes to `sphinx_design/static/sphinx-design.min.css`
 4. Test with different themes to ensure compatibility
 
 ## Reference Documentation

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- ♻️ IMPROVE: Static assets (CSS/JS) are now served via Sphinx's standard
+  `html_static_path` mechanism, rather than being written directly into the
+  build output; non-HTML builds no longer gain a spurious
+  `_sphinx_design_static` directory ({pr}`276`, {issue}`200`, {issue}`235`).
+  A stale `_sphinx_design_static` directory left in an existing HTML build
+  directory by previous versions is unused and can safely be deleted.
+- ⬆️ UPGRADE: Sphinx `>=7.2` is now required ({pr}`276`)
+- 🗑️ REMOVE: The private `sphinx_design._compat.findall` helper has been
+  removed (docutils `Element.findall` is guaranteed by the Sphinx floor);
+  any code importing it should call `node.findall(...)` directly ({pr}`276`)
 - 🐛 FIX: buttons are no longer destroyed by gettext translation:
   translated `button-link`/`button-ref` keep their styling and links
   (gettext now targets only the button text), thanks to {user}`sneakers-the-rat`

package.json

@@ -3,7 +3,7 @@
   "version": "0.0.1",
   "description": "Scripts for compiling the sphinx-design assets",
   "scripts": {
-    "css": "sass --style=compressed --no-source-map style/index.scss sphinx_design/compiled/style.min.css"
+    "css": "sass --style=compressed --no-source-map style/index.scss sphinx_design/static/sphinx-design.min.css"
   },
   "dependencies": {
     "sass": "^1.35.2"

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
 ]
 keywords = ["sphinx", "extension", "material design", "web components"]
 requires-python = ">=3.11"
-dependencies = ["sphinx>=7,<10"]
+dependencies = ["sphinx>=7.2,<10"]
 
 [project.urls]
 Homepage = "https://github.com/executablebooks/sphinx-design"

sphinx_design/_compat.py

@@ -1,17 +1,7 @@
 """Helpers for cross compatibility across dependency versions."""
 
-from collections.abc import Callable, Iterable
 from importlib import resources
 
-from docutils.nodes import Element
-
-
-def findall(node: Element) -> Callable[..., Iterable[Element]]:
-    """Iterate through"""
-    # findall replaces traverse in docutils v0.18
-    # note a difference is that findall is an iterator
-    return getattr(node, "findall", node.traverse)
-
 
 def read_text(module: resources.Package, filename: str) -> str:
     return resources.files(module).joinpath(filename).read_text()

sphinx_design/cards.py

@@ -9,7 +9,6 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.logging import getLogger
 
-from ._compat import findall
 from .shared import (
     WARNING_TYPE,
     PassthroughTextElement,
@@ -247,9 +246,9 @@ def _create_component(
     @staticmethod
     def add_card_child_classes(node):
         """Add classes to specific child nodes."""
-        for para in findall(node)(nodes.paragraph):
+        for para in node.findall(nodes.paragraph):
             para["classes"] = [*para.get("classes", []), "sd-card-text"]
-        # for title in findall(node)(nodes.title):
+        # for title in node.findall(nodes.title):
         #     title["classes"] = ([] if "classes" not in title else title["classes"]) + [
         #         "sd-card-title"
         #     ]

sphinx_design/dropdown.py

@@ -16,7 +16,6 @@
     margin_option,
 )
 
-from ._compat import findall
 from .icons import get_octicon, list_octicons
 
 
@@ -153,7 +152,7 @@ class DropdownHtmlTransform(SphinxPostTransform):
     def run(self, **kwargs: Any) -> None:
         """Run the transform"""
         document: nodes.document = self.document
-        for node in findall(document)(lambda node: is_component(node, "dropdown")):
+        for node in document.findall(lambda node: is_component(node, "dropdown")):
             # TODO option to not have card css (but requires more formatting)
             use_card = True
 
@@ -230,7 +229,7 @@ def run(self, **kwargs: Any) -> None:
                 children=body_children,
             )
             if use_card:
-                for para in findall(body_node)(nodes.paragraph):
+                for para in body_node.findall(nodes.paragraph):
                     para["classes"] = ([] if "classes" in para else para["classes"]) + [
                         "sd-card-text"
                     ]

sphinx_design/extension.py

@@ -1,17 +1,12 @@
 from contextlib import contextmanager
 from functools import partial
-import hashlib
 from pathlib import Path
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from sphinx import version_info as sphinx_version
 from sphinx.application import Sphinx
-from sphinx.environment import BuildEnvironment
 from sphinx.transforms import SphinxTransform
 
-from . import compiled as static_module
-from ._compat import findall, read_text
 from .article_info import setup_article_info
 from .badges_buttons import setup_badges_and_buttons
 from .cards import setup_cards
@@ -27,12 +22,13 @@
 )
 from .tabs import setup_tabs
 
+STATIC_DIR = Path(__file__).parent / "static"
+
 
 def setup_extension(app: Sphinx) -> None:
     """Set up the sphinx extension."""
     setup_sd_config(app)
-    app.connect("builder-inited", update_css_js)
-    app.connect("env-updated", update_css_links)
+    app.connect("builder-inited", add_static_assets)
     # we override container html visitors, to stop the default behaviour
     # of adding the `container` class to all nodes.container
     app.add_node(
@@ -77,45 +73,13 @@ def _add_directive(name, directive, **kwargs):
     app.add_directive = add_directive  # type: ignore[method-assign]
 
 
-def update_css_js(app: Sphinx):
-    """Copy the CSS to the build directory."""
-    # reset changed identifier
-    app.env.sphinx_design_css_changed = False  # type: ignore[attr-defined]
-    # setup up new static path in output dir
-    static_path = (Path(app.outdir) / "_sphinx_design_static").absolute()
-    static_existed = static_path.exists()
-    static_path.mkdir(exist_ok=True)
-    app.config.html_static_path.append(str(static_path))
-    # Copy JS to the build directory.
-    js_path = static_path / "design-tabs.js"
-    app.add_js_file(js_path.name)
-    if not js_path.exists():
-        content = read_text(static_module, "sd_tabs.js")
-        js_path.write_text(content)
-    # Read the css content and hash it
-    content = read_text(static_module, "style.min.css")
-    # Write the css file
-    if sphinx_version < (7, 1):
-        hash = hashlib.md5(content.encode("utf8"), usedforsecurity=False).hexdigest()
-        css_path = static_path / f"sphinx-design.{hash}.min.css"
-    else:
-        # since sphinx 7.1 a checksum is added to the css file URL, so there is no need to do it here
-        # https://github.com/sphinx-doc/sphinx/pull/11415
-        css_path = static_path / "sphinx-design.min.css"
-    app.add_css_file(css_path.name)
-    if css_path.exists():
+def add_static_assets(app: Sphinx) -> None:
+    """Register the extension's static assets (HTML-format builders only)."""
+    if app.builder.format != "html":
         return
-    if static_existed:
-        app.env.sphinx_design_css_changed = True  # type: ignore[attr-defined]
-    for path in static_path.glob("*.css"):
-        path.unlink()
-    css_path.write_text(content, encoding="utf8")
-
-
-def update_css_links(app: Sphinx, env: BuildEnvironment):
-    """If CSS has changed, all files must be re-written, to include the correct stylesheets."""
-    if env.sphinx_design_css_changed:  # type: ignore[attr-defined]
-        return list(env.all_docs.keys())
+    app.config.html_static_path.append(str(STATIC_DIR))
+    app.add_css_file("sphinx-design.min.css")
+    app.add_js_file("design-tabs.js")
 
 
 def visit_container(self, node: nodes.Node):
@@ -175,15 +139,15 @@ class AddFirstTitleCss(SphinxTransform):
 
     def apply(self):
         hide = False
-        for docinfo in findall(self.document)(nodes.docinfo):
-            for name in findall(docinfo)(nodes.field_name):
+        for docinfo in self.document.findall(nodes.docinfo):
+            for name in docinfo.findall(nodes.field_name):
                 if name.astext() == "sd_hide_title":
                     hide = True
                     break
             break
         if not hide:
             return
-        for section in findall(self.document)(nodes.section):
+        for section in self.document.findall(nodes.section):
             if isinstance(section.children[0], nodes.title):
                 if "classes" in section.children[0]:
                     section.children[0]["classes"].append("sd-d-none")