fix: scrolltop button (#2012)

Re-implement the `show_scrolltop` functionality. I _think_ I wanted to remove the scroll to top button with version 5, but I left in the template and configuration option. Since it was documented behavior, I treated this as a bug and re-implemented the behavior with Alpine. Fixes #1981.
kai687 · Oct 4, 2024 · beebf4b · beebf4b
1 parent 12a42cd
commit beebf4b
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 7 deletions.
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sphinxawesome-theme"
-version = "5.3.0"
+version = "5.3.1"
 description = "An awesome theme for the Sphinx documentation generator"
 readme = "README.md"
 authors = ["Kai Welke <[email protected]>"]

diff --git a/src/sphinxawesome_theme/layout.html b/src/sphinxawesome_theme/layout.html
@@ -84,7 +84,9 @@
 
     {%- block extrahead %}{%- endblock extrahead %}
 </head>
-<body x-data="{ showSidebar: false }" class="min-h-screen font-sans antialiased bg-background text-foreground" :class="{ 'overflow-hidden': showSidebar }">
+  <body x-data="{ showSidebar: false, showScrollTop: false }" class="min-h-screen font-sans antialiased bg-background text-foreground" :class="{ 'overflow-hidden': showSidebar }"
+    {%- if theme_show_scrolltop|tobool -%}@scroll.window="showScrollTop = pageYOffset > 100"{%- endif -%}
+  >
 
   {#- A blurry background screen for the mobile sidebar -#}
   {%- if sidebars|length > 0 %}
@@ -131,6 +133,9 @@
       {%- include "footer.html" %}
     {%- endblock footer %}
   </div>
+  {%- if theme_show_scrolltop|tobool %}
+    {%- include "scrolltop.html" %}
+  {%- endif %}
   {% block scripts %}
   {%- for js in script_files %}
     {{ js_tag(js) }}

diff --git a/src/sphinxawesome_theme/scrolltop.html b/src/sphinxawesome_theme/scrolltop.html
@@ -1,9 +1,12 @@
 {#-
 A `scroll to top` button. Is shown at the bottom right if `show_scrolltop` is true.
 -#}
-<button data-scroll-to-top-target="scrollToTop"
-        data-action="scroll-to-top#scroll"
-        class="fixed bottom-8 right-8 p-2 z-10 rounded-sm bg-gray-700 text-xs text-white invisible opacity-0 transition-all duration-1000 hover:bg-gray-950 focus:bg-gray-950">
+<button id="scrolltop"
+        x-cloak
+        @click="window.scrollTo({top: 0, behavior: 'smooth'})"
+        class="fixed bottom-8 right-8 p-2 z-10 rounded-sm bg-gray-700 text-xs text-white transition-all duration-1000 hover:bg-gray-950 focus:bg-gray-950"
+        :class="{'opacity-0 invisible' : !showScrollTop}"
+>
   <svg xmlns="http://www.w3.org/2000/svg"
        height="14"
        viewBox="0 96 960 960"

diff --git a/src/theme-src/package.json b/src/theme-src/package.json
@@ -1,6 +1,6 @@
 {
   "name": "sphinxawesome-theme",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "scripts": {
     "build": "NODE_ENV=production webpack",
     "dev": "NODE_ENV=development webpack --watch --progress",

diff --git a/tests/test_basic.py b/tests/test_basic.py
@@ -11,7 +11,7 @@
 
 def test_returns_version() -> None:
     """It has the correct version."""
-    assert sphinxawesome_theme.__version__ == "5.3.0"
+    assert sphinxawesome_theme.__version__ == "5.3.1"
 
 
 @pytest.mark.sphinx("dummy")

diff --git a/tests/test_scrolltop.py b/tests/test_scrolltop.py
@@ -0,0 +1,40 @@
+"""Test the presence or absense of the scroll to top button."""
+
+import os
+from pathlib import Path
+
+import pytest
+from sphinx.application import Sphinx
+
+from .util import parse_html
+
+
+@pytest.mark.sphinx(
+    "html",
+    confoverrides={
+        "html_theme": "sphinxawesome_theme",
+    },
+)
+def test_no_scroll_top_button(app: Sphinx) -> None:
+    """It doesn't have a scroll to top button by default."""
+    app.build()
+    assert os.path.exists(Path(app.outdir) / "index.html")
+    tree = parse_html(Path(app.outdir) / "index.html")
+    button = tree.select("button#scrolltop")
+    assert len(button) == 0
+
+
+@pytest.mark.sphinx(
+    "html",
+    confoverrides={
+        "html_theme": "sphinxawesome_theme",
+        "html_theme_options": {"show_scrolltop": True},
+    },
+)
+def test_scroll_top_button(app: Sphinx) -> None:
+    """It shows a scroll to top button."""
+    app.build()
+    assert os.path.exists(Path(app.outdir) / "index.html")
+    tree = parse_html(Path(app.outdir) / "index.html")
+    button = tree.select("button#scrolltop")
+    assert len(button) == 1