Merge branch 'master' into MAINT_switch_prettier_fork

Author: choldgraf

.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/[email protected]
       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/components/source-files.md

@@ -48,7 +48,7 @@ Once this is provided, you may add source buttons by following the following sec
 (source-buttons:source)=
 ## Add a button to the page source
 
-Show the raw source of the page on the provider you've proivded.
+Show the raw source of the page on the provider you've provided.
 To add a button to the page source, first [configure your source repository](source-buttons:repository) and then add:
 
 ```python

docs/content/launch.md

@@ -2,11 +2,13 @@
 # Launch buttons for interactivity
 
 You can automatically add buttons that allow users to interact with your
-book's content. This is either by directing them to a BinderHub or JupyterHub
-that runs in the cloud, or by making your page interactive using Thebe.
+book's content. This is can be by directing them to
+a [JupyterLite](https://jupyterlite.readthedocs.io) installation (that runs in
+the user's browser) or one of BinderHub or JupyterHub (that runs in the
+cloud), or by making your page interactive using Thebe.
 
-To use either Binder or JupyterHub links, you'll first need to configure your
-documentation's repository url:
+To use any of JupyterLite or Binder or JupyterHub links, you'll first need to
+configure your documentation's repository url:
 
 ```python
 html_theme_options = {
@@ -26,6 +28,28 @@ folder as your content, then Binder/JupyterHub links will point to the ipynb
 file instead of the text file.
 ```
 
+## JupyterLite
+
+If you are adding [JupyterLite](https://github.com/jupyterlite/jupyterlite) links to your page, first work out where your
+JupyterLite instance will be serving from, then add the URL to your
+configuration. In the example below, we've set up JupyterLite pages at the
+base URL of the main pages site, and at subdirectory `interact/lab`:
+
+```python
+html_theme_options = {
+    ...
+    "launch_buttons": {
+        "jupyterlite_url": "interact/lab/index.html"
+    },
+    ...
+}
+```
+
+See <https://odsti.github.io/cfd-textbook> for an example
+[JupyterBook](https://jupyterbook.org) project serving JupyterLite using this
+configuration, and <https://github.com/odsti/cfd-textbook> for the driving
+repository.
+
 ## Binder / BinderHub
 
 To add Binder links to your page, add the following configuration:

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

@@ -25,7 +25,8 @@ filterwarnings = [
   # Sphinx triggers this
   '''ignore:'imghdr' is deprecated and slated for removal in Python 3\.13:DeprecationWarning''',
   '''ignore:'sphinx.util.import_object' is deprecated.:PendingDeprecationWarning''',
-  'ignore:Parsing dates involving a day of month without a year specified is ambiguious:DeprecationWarning'
+  'ignore:Parsing dates involving a day of month without a year specified is ambiguious:DeprecationWarning',
+  'ignore:Argument "parser_name" will be removed in Docutils 2.0.:PendingDeprecationWarning',
 ]
 
 [project]
@@ -37,7 +38,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);
+    }
+  }
+}