prepare for latest pydata and python releases

.github/workflows/tests.yml

@@ -28,27 +28,16 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.10", "3.11", "3.12.*", "3.13"]
-        # Only test the latest major release of Sphinx because otherwise we need to
-        # keep multiple versions of regression tests on file and this creates lots of
-        # noise in the tests.
-        sphinx: ["~=6.0","~=7.0", "~=8.0"]
+        python-version: ["3.11", "3.12", "3.13"]
+        # Test last 2 major releases of Sphinx; regression fixtures target the latest.
+        sphinx: ["~=7.0", "~=8.0"]
         include:
         - os: windows-latest
-          # Python 3.12 is broken on windows builds until the following PR is released:
-          # https://github.com/pradyunsg/sphinx-theme-builder/pull/47
-          python-version: 3.11
+          python-version: 3.13
           # Windows pulling in dependencies fails
           experimental: true
         - os: macos-latest
           python-version: 3.x
-        # Sphinx <8 is 3.9+
-        - os: ubuntu-latest
-          python-version: "3.9"
-          sphinx: "~=7.0"
-        - os: ubuntu-latest
-          python-version: "3.9"
-          sphinx: "~=6.0"
 
     runs-on: ${{ matrix.os }}
 
@@ -73,10 +62,10 @@ jobs:
     # Only upload to codecov on pull requests so that we don't trigger rate limit blocks
     # Disabled for now with false &&
     - name: Upload to Codecov
-      if: false && matrix.os == 'ubuntu-latest' && matrix.python-version == 3.9 && matrix.sphinx == '~=7.0' && github.repository == 'executablebooks/sphinx-book-theme' && github.event_name == 'pull_request'
+      if: false && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' && matrix.sphinx == '~=8.0' && github.repository == 'executablebooks/sphinx-book-theme' && github.event_name == 'pull_request'
       uses: codecov/codecov-action@v5.0.7
       with:
-        name: ebp-sbt-pytests-py3.7
+        name: ebp-sbt-pytests-py3.11
         flags: pytests
         file: ./coverage.xml
         fail_ci_if_error: true
@@ -90,7 +79,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.9'
+        python-version: '3.13'
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
     - name: Install fonts

ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 This is a short overview of the general architecture and structure of the repository, to help you orient yourself.
 
-This theme uses [sphinx-theme-builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) as its build backend, and follows the [filesystem layout](https://sphinx-theme-builder.readthedocs.io/en/latest/filesystem-layout/) recommended by it.
+This theme uses [sphinx-theme-builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) as its build backend, and follows the [filesystem layout](https://sphinx-theme-builder.readthedocs.io/en/latest/filesystem-layout.html) recommended by it.
 See below for some more specific sections
 
 ```{contents}

README.md

@@ -2,6 +2,9 @@
 
 [![codecov][codecov-badge]][codecov-link] [![Documentation Status][rtd-badge]][rtd-link] [![PyPI][pypi-badge]][pypi-link]
 
+> [!NOTE]
+> **Maintenance Mode**: This project is currently in maintenance mode. We are accepting bug fixes as best we can, but there are not dedicated resources to review and merge. New feature development is not likely. If you're interested in becoming a maintainer and helping keep this project actively developed, please reach out by opening an issue!
+
 **An interactive book theme for Sphinx**.
 
 This is a lightweight Sphinx theme designed to mimic the look-and-feel of an

docs/contributing/tests.md

@@ -14,8 +14,8 @@ $ tox
 You can specify a specific environment like so:
 
 ```console
-# Run the tests with Python 3.9, Sphinx 4
-$ tox -e py39-sphinx4
+# Run the tests with Python 3.10, Sphinx 6
+$ tox -e py310-sphinx6
 ```
 
 ## List all test environments
@@ -46,7 +46,7 @@ By default, `tox` will only install the necessary environment **once**.
 If you'd like to force a re-build, use the `-r` parameter. For example:
 
 ```console
-$ tox -r -e py38-sphinx3
+$ tox -r -e py310-sphinx6
 ```
 
 ## Test audits with lighthouse
@@ -63,8 +63,8 @@ To preview the output of these tests:
 
 ## Test multiple Sphinx versions
 
-This theme is tested against the latest two major versions of Sphinx.
-We try to set up our regression tests such that there are no differences between these two Sphinx versions.
+This theme is tested against Sphinx 6-9.
+We try to set up our regression tests such that there are no differences between these Sphinx versions.
 
 ### Unit tests
 
@@ -73,9 +73,9 @@ Use the variable `sphinx_build.software_versions` to conditionally run tests bas
 For example:
 
 ```python
-if sphinx_build.software_versions == ".sphinx3":
+if sphinx_build.software_versions == ".sphinx8":
    foo
-elif sphinx_build.software_versions == ".sphinx4":
+elif sphinx_build.software_versions == ".sphinx9":
    bar
 ```
 

docs/reference/extensions.md

@@ -108,4 +108,25 @@ This toggle is in the margin!
 
 ## `sphinx-design` for UI components
 
+[`sphinx-design`](https://sphinx-design.readthedocs.io/) provides various UI components like badges, cards, and dropdowns.
+
+**Badge:**
+
 {bdg-primary}`Test badge`.
+
+**Card:**
+
+::::{card} Card Title
+:class-card: sd-border-0
+Card header.
+^^^
+Card content goes here. This demonstrates how cards look in both light and dark modes.
++++
+Card footer.
+::::
+
+**Dropdown:**
+
+:::{dropdown} Click to expand
+This is the dropdown content. It should be readable in both light and dark modes.
+:::

pyproject.toml

@@ -37,7 +37,7 @@ readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
   "sphinx>=6.1",
-  "pydata-sphinx-theme==0.15.4"
+  "pydata-sphinx-theme==0.16.1"
 ]
 
 license = { file = "LICENSE" }

src/sphinx_book_theme/assets/scripts/index.js

@@ -181,8 +181,70 @@ function addNoPrint() {
 window.initThebeSBT = initThebeSBT;
 window.toggleFullScreen = toggleFullScreen;
 
+/**
+ * Add blur behavior to buttons with tooltips
+ * This prevents tooltips from persisting after clicking buttons
+ */
+function addBlurToButtons() {
+  // List of button selectors that should blur on click to dismiss tooltips
+  const buttonSelectors = [
+    ".theme-switch-button",
+    ".search-button",
+    ".primary-toggle",
+    ".secondary-toggle",
+  ];
+
+  // Add blur on click for each button type
+  buttonSelectors.forEach((selector) => {
+    const button = document.querySelector(selector);
+    if (button) {
+      button.addEventListener(
+        "click",
+        () => {
+          button.blur();
+        },
+        true,
+      );
+    }
+  });
+}
+
+/**
+ * Fix sidebar toggle behavior for wide screens
+ * On wide screens (>= 992px), clicking the toggle should collapse the sidebar,
+ * not open it as a dialog modal. The dialog behavior is only for narrow screens.
+ */
+function fixSidebarToggle() {
+  const primaryToggle = document.querySelector(".primary-toggle");
+  const primarySidebar = document.querySelector("#pst-primary-sidebar");
+  const primaryDialog = document.querySelector("#pst-primary-sidebar-modal");
+
+  // Fix primary sidebar toggle
+  if (primaryToggle && primarySidebar && primaryDialog) {
+    // Intercept clicks on the toggle button BEFORE pydata-sphinx-theme's handler
+    primaryToggle.addEventListener(
+      "click",
+      (event) => {
+        const isWideScreen = window.matchMedia("(min-width: 992px)").matches;
+
+        if (isWideScreen) {
+          // On wide screens, prevent the dialog from opening and toggle sidebar visibility instead
+          event.preventDefault();
+          event.stopImmediatePropagation();
+
+          // Toggle a class to hide/show the sidebar
+          primarySidebar.classList.toggle("pst-sidebar-hidden");
+        }
+      },
+      true,
+    ); // Use capture phase to run before PST's handler
+  }
+}
+
 /**
  * Set up functions to load when the DOM is ready
  */
 sbRunWhenDOMLoaded(initTocHide);
 sbRunWhenDOMLoaded(addNoPrint);
+sbRunWhenDOMLoaded(addBlurToButtons);
+sbRunWhenDOMLoaded(fixSidebarToggle);

src/sphinx_book_theme/assets/styles/content/_admonitions.scss

@@ -0,0 +1,29 @@
+/**
+ * Standard Sphinx admonitions
+ * Improves contrast and readability in dark mode
+ * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743
+ */
+
+// Ensure admonition titles have proper contrast in dark mode
+html[data-theme="dark"] {
+  .admonition {
+    .admonition-title {
+      // Ensure text is always readable by using a color that contrasts well
+      // with the admonition background colors
+      color: var(--pst-color-text-base);
+
+      // Add a slight text shadow for better readability on colored backgrounds
+      text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
+    }
+  }
+}
+
+// Light mode improvements for consistency
+html[data-theme="light"] {
+  .admonition {
+    .admonition-title {
+      // Ensure consistent text rendering
+      color: var(--pst-color-text-base);
+    }
+  }
+}

src/sphinx_book_theme/assets/styles/extensions/_myst-nb.scss

@@ -0,0 +1,18 @@
+/**
+ * MyST-NB extension
+ * Improves contrast and readability in dark mode
+ * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743
+ */
+
+// Ensure hide-input tags have proper contrast in dark mode
+html[data-theme="dark"] {
+  .tag_hide_input .cell_input {
+    summary {
+      color: var(--pst-color-link);
+
+      &:hover {
+        color: var(--pst-color-link-hover);
+      }
+    }
+  }
+}

src/sphinx_book_theme/assets/styles/extensions/_sphinx-design.scss

@@ -0,0 +1,18 @@
+/**
+ * sphinx-design extension
+ * Improves contrast and readability in dark mode
+ * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743
+ */
+
+// Ensure sphinx-design cards and dropdowns have proper contrast in dark mode
+html[data-theme="dark"] {
+  .sd-card,
+  .sd-dropdown {
+    .sd-card-header,
+    .sd-card-title,
+    .sd-summary-title {
+      color: var(--pst-color-text-base);
+      text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
+    }
+  }
+}

src/sphinx_book_theme/assets/styles/extensions/_sphinx-tabs.scss

@@ -0,0 +1,34 @@
+/**
+ * sphinx-tabs extension
+ * Improves contrast and readability in dark mode
+ * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743
+ */
+
+// Ensure sphinx-tabs have proper contrast in dark mode
+html[data-theme="dark"] {
+  .sphinx-tabs {
+    // Tab buttons
+    .sphinx-tabs-tab {
+      background-color: var(--pst-color-surface);
+      color: var(--pst-color-text-muted);
+      border-color: var(--pst-color-border);
+
+      &[aria-selected="true"] {
+        background-color: var(--pst-color-background);
+        color: var(--pst-color-text-base);
+        border-bottom-color: var(--pst-color-background);
+      }
+
+      &:hover {
+        color: var(--pst-color-text-base);
+      }
+    }
+
+    // Tab panel content area
+    .sphinx-tabs-panel {
+      background-color: var(--pst-color-background);
+      color: var(--pst-color-text-base);
+      border-color: var(--pst-color-border);
+    }
+  }
+}

src/sphinx_book_theme/assets/styles/extensions/_sphinx-togglebutton.scss

@@ -0,0 +1,19 @@
+/**
+ * sphinx-togglebutton extension
+ * Improves contrast and readability in dark mode
+ * Fixes: https://github.com/executablebooks/sphinx-book-theme/issues/743
+ */
+
+// Ensure toggle button expand links have proper contrast in dark mode
+html[data-theme="dark"] {
+  details.above-input,
+  details.below-input {
+    summary {
+      color: var(--pst-color-link);
+
+      &:hover {
+        color: var(--pst-color-link-hover);
+      }
+    }
+  }
+}

src/sphinx_book_theme/assets/styles/index.scss

@@ -33,6 +33,7 @@
 @use "components/search";
 
 // Content blocks in standard Sphinx
+@use "content/admonitions";
 @use "content/images";
 @use "content/margin";
 @use "content/quotes";
@@ -42,4 +43,8 @@
 // Content blocks from Sphinx extensions
 
 @use "extensions/comments";
+@use "extensions/myst-nb";
+@use "extensions/sphinx-design";
+@use "extensions/sphinx-tabs";
+@use "extensions/sphinx-togglebutton";
 @use "extensions/thebe";

src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss

@@ -18,6 +18,15 @@
     opacity variables.$animation-time ease 0s,
     visibility variables.$animation-time ease 0s;
 
+  // Hide sidebar when toggle button is clicked on wide screens
+  &.pst-sidebar-hidden {
+    @media (min-width: variables.$breakpoint-lg) {
+      margin-left: -(variables.$sidebar-primary-width-widescreen);
+      visibility: hidden;
+      opacity: 0;
+    }
+  }
+
   @media (max-width: variables.$breakpoint-md) {
     // So that tooltips don't overlap
     z-index: variables.$zindex-tooltip + 1;
@@ -28,6 +37,13 @@
     border-top: none;
   }
 
+  // Left-align icon badges with standard gap spacing instead of centering
+  .navbar-icon-links {
+    display: flex !important;
+    justify-content: flex-start !important;
+    gap: 0.5rem !important;
+  }
+
   // On wide screens we have a smaller sidebar width than PST
   @media (min-width: variables.$breakpoint-lg) {
     flex-basis: variables.$sidebar-primary-width-widescreen;