From 1dcc23165d9ed6488ce70d6f1ea8fe75673a17e1 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 10:04:36 -0800 Subject: [PATCH 01/17] Update HTML for latest pydata and sphinx --- .github/workflows/tests.yml | 13 ++- docs/contributing/tests.md | 14 +-- pyproject.toml | 2 +- .../components/page-toc.html | 7 +- tests/test_build.py | 4 +- tests/test_build/build__header-article.html | 28 +++--- .../build__pagetoc--page-multipletitles.html | 6 +- .../build__pagetoc--page-onetitle.html | 6 +- .../build__sidebar-primary__nav.html | 96 +++++++++++++++++++ .../header__repo-buttons--all-off.html | 28 +++--- .../header__repo-buttons--all-on.html | 28 +++--- .../header__repo-buttons--custom-branch.html | 28 +++--- .../header__repo-buttons--one-on.html | 28 +++--- .../test_build/test_right_sidebar_title.html | 2 +- tox.ini | 6 +- 15 files changed, 190 insertions(+), 106 deletions(-) create mode 100644 tests/test_build/build__sidebar-primary__nav.html diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1428b1054..bfa87724d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -29,10 +29,15 @@ jobs: 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"] + # Test recent major releases of Sphinx; regression fixtures target the latest. + sphinx: ["~=6.0","~=7.0", "~=8.0", "~=9.0"] + exclude: + - os: ubuntu-latest + python-version: "3.10" + sphinx: "~=9.0" + - os: ubuntu-latest + python-version: "3.11" + sphinx: "~=9.0" include: - os: windows-latest # Python 3.12 is broken on windows builds until the following PR is released: diff --git a/docs/contributing/tests.md b/docs/contributing/tests.md index d315aa212..d3389324e 100644 --- a/docs/contributing/tests.md +++ b/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 ``` diff --git a/pyproject.toml b/pyproject.toml index 290291cff..2c255d740 100644 --- a/pyproject.toml +++ b/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" } diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html index e0dbff434..1589f71d3 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/page-toc.html @@ -6,10 +6,13 @@ -#} {% set page_toc = generate_toc_html() %} {%- if page_toc | length >= 1 %} -
+{%- set page_navigation_heading_id = unique_html_id("pst-page-navigation-heading") -%} + -
diff --git a/tests/test_build/build__pagetoc--page-multipletitles.html b/tests/test_build/build__pagetoc--page-multipletitles.html index be65805e2..5a02f2ea1 100644 --- a/tests/test_build/build__pagetoc--page-multipletitles.html +++ b/tests/test_build/build__pagetoc--page-multipletitles.html @@ -1,12 +1,12 @@ -
+
diff --git a/tests/test_build/header__repo-buttons--one-on.html b/tests/test_build/header__repo-buttons--one-on.html index cf45b8dca..a62cf6e31 100644 --- a/tests/test_build/header__repo-buttons--one-on.html +++ b/tests/test_build/header__repo-buttons--one-on.html @@ -43,22 +43,18 @@ - - + +
diff --git a/tests/test_build/test_right_sidebar_title.html b/tests/test_build/test_right_sidebar_title.html index 7c1d278bb..0c251de5b 100644 --- a/tests/test_build/test_right_sidebar_title.html +++ b/tests/test_build/test_right_sidebar_title.html @@ -1,4 +1,4 @@ -
+
My test content title diff --git a/tox.ini b/tox.ini index 10492c43a..df6f4ac83 100644 --- a/tox.ini +++ b/tox.ini @@ -45,9 +45,9 @@ deps = commands = stb serve docs --open-browser -[testenv:py{39,310,311}-sphinx{5,6}] +[testenv:py{39,310,311}-sphinx{6,7}] extras = test deps = - sphinx5: sphinx>=5,<6 - sphinx6: sphinx>=6,<7 + sphinx6: sphinx>=6.1,<7 + sphinx7: sphinx>=7,<8 commands = pytest {posargs} From 23c8441cd425d0feb87027ad52a316a88c335b9d Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 10:04:47 -0800 Subject: [PATCH 02/17] Fix primary sidebar button toggle behavior --- src/sphinx_book_theme/assets/scripts/index.js | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/src/sphinx_book_theme/assets/scripts/index.js b/src/sphinx_book_theme/assets/scripts/index.js index 372e2639b..150b1e27e 100644 --- a/src/sphinx_book_theme/assets/scripts/index.js +++ b/src/sphinx_book_theme/assets/scripts/index.js @@ -181,8 +181,50 @@ function addNoPrint() { window.initThebeSBT = initThebeSBT; window.toggleFullScreen = toggleFullScreen; +/** + * 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 secondaryToggle = document.querySelector('.secondary-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'); + } + + // Blur the button so it loses focus and tooltip dismisses naturally + // This works for both wide screens (after collapse) and narrow screens (before dialog opens) + primaryToggle.blur(); + }, true); // Use capture phase to run before PST's handler + } + + // Fix secondary sidebar toggle + if (secondaryToggle) { + secondaryToggle.addEventListener('click', () => { + // Blur the button so tooltip dismisses naturally + secondaryToggle.blur(); + }, true); + } +} + /** * Set up functions to load when the DOM is ready */ sbRunWhenDOMLoaded(initTocHide); sbRunWhenDOMLoaded(addNoPrint); +sbRunWhenDOMLoaded(fixSidebarToggle); From efd01b4abe1a2f950f036e10b4195765d3d72bdf Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 10:20:21 -0800 Subject: [PATCH 03/17] Left-align the icon links in the sidebar --- .../assets/styles/sections/_sidebar-primary.scss | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss index f446759f4..fc6af6302 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss @@ -28,6 +28,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; From 4289e33dadd289b7d335f0202032a9fa20faac88 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 10:22:43 -0800 Subject: [PATCH 04/17] Hide the sidebar on click on wide screens --- .../assets/styles/sections/_sidebar-primary.scss | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss index fc6af6302..ba026a3ce 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-primary.scss +++ b/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; From f80780d37cd14694c699acaed6192023c8991843 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 14:50:01 -0800 Subject: [PATCH 05/17] Add note about maintenance mode --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index cc24ca2be..5723650f6 100644 --- a/README.md +++ b/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 From 0b969d53fe8023a5ff7adebdf0c90c3e45e7abd5 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 15:02:33 -0800 Subject: [PATCH 06/17] Fix blur for buttons --- src/sphinx_book_theme/assets/scripts/index.js | 38 ++++++++++++------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/src/sphinx_book_theme/assets/scripts/index.js b/src/sphinx_book_theme/assets/scripts/index.js index 150b1e27e..cd804828a 100644 --- a/src/sphinx_book_theme/assets/scripts/index.js +++ b/src/sphinx_book_theme/assets/scripts/index.js @@ -181,6 +181,30 @@ 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, @@ -188,7 +212,6 @@ window.toggleFullScreen = toggleFullScreen; */ function fixSidebarToggle() { const primaryToggle = document.querySelector('.primary-toggle'); - const secondaryToggle = document.querySelector('.secondary-toggle'); const primarySidebar = document.querySelector('#pst-primary-sidebar'); const primaryDialog = document.querySelector('#pst-primary-sidebar-modal'); @@ -206,20 +229,8 @@ function fixSidebarToggle() { // Toggle a class to hide/show the sidebar primarySidebar.classList.toggle('pst-sidebar-hidden'); } - - // Blur the button so it loses focus and tooltip dismisses naturally - // This works for both wide screens (after collapse) and narrow screens (before dialog opens) - primaryToggle.blur(); }, true); // Use capture phase to run before PST's handler } - - // Fix secondary sidebar toggle - if (secondaryToggle) { - secondaryToggle.addEventListener('click', () => { - // Blur the button so tooltip dismisses naturally - secondaryToggle.blur(); - }, true); - } } /** @@ -227,4 +238,5 @@ function fixSidebarToggle() { */ sbRunWhenDOMLoaded(initTocHide); sbRunWhenDOMLoaded(addNoPrint); +sbRunWhenDOMLoaded(addBlurToButtons); sbRunWhenDOMLoaded(fixSidebarToggle); From d23d013c9a25906574152f90cfd49cba820a3071 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 15:02:43 -0800 Subject: [PATCH 07/17] Update the test versions we run --- .github/workflows/tests.yml | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index bfa87724d..b9848a7f2 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -28,32 +28,16 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest] - python-version: ["3.10", "3.11", "3.12.*", "3.13"] - # Test recent major releases of Sphinx; regression fixtures target the latest. - sphinx: ["~=6.0","~=7.0", "~=8.0", "~=9.0"] - exclude: - - os: ubuntu-latest - python-version: "3.10" - sphinx: "~=9.0" - - os: ubuntu-latest - python-version: "3.11" - sphinx: "~=9.0" + python-version: ["3.11", "3.12", "3.13"] + # Test last 2 major releases of Sphinx; regression fixtures target the latest. + sphinx: ["~=8.0", "~=9.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 # 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 }} @@ -78,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 @@ -95,7 +79,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: '3.9' + python-version: '3.11' cache: "pip" cache-dependency-path: "pyproject.toml" - name: Install fonts From 94b809136bc7c253fcee1d6c5ed72c29bfaba0f1 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 15:17:50 -0800 Subject: [PATCH 08/17] Standardize icon classes --- src/sphinx_book_theme/header_buttons/__init__.py | 1 + .../sphinx_book_theme/components/toggle-secondary-sidebar.html | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/src/sphinx_book_theme/header_buttons/__init__.py b/src/sphinx_book_theme/header_buttons/__init__.py index 3da1736a8..8bd14a0c6 100644 --- a/src/sphinx_book_theme/header_buttons/__init__.py +++ b/src/sphinx_book_theme/header_buttons/__init__.py @@ -117,6 +117,7 @@ def add_header_buttons(app, pagename, templatename, context, doctree): "tooltip": translation("Fullscreen mode"), "icon": "fas fa-expand", "label": "fullscreen-button", + "classes": "pst-navbar-icon", } ) diff --git a/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html b/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html index 3bca57165..cfbf0978a 100644 --- a/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html +++ b/src/sphinx_book_theme/theme/sphinx_book_theme/components/toggle-secondary-sidebar.html @@ -1,7 +1,7 @@ {# The in-page Table of Contents -#} {% set page_toc = generate_toc_html() -%} {% if page_toc -%} - {%- endif %} From ea95085989ea406a09ff321eef2ad708cc199e3d Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 15:20:12 -0800 Subject: [PATCH 09/17] Fix sidebar padding --- .../assets/styles/sections/_sidebar-secondary.scss | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss index 103bb1ab6..e93cfac82 100644 --- a/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss +++ b/src/sphinx_book_theme/assets/styles/sections/_sidebar-secondary.scss @@ -46,8 +46,8 @@ // To make sure it shows above the page content z-index: variables.$zindex-middle; - // Remove padding so that it's flush on the top and left - padding: 0; + // Add comfortable horizontal padding, keep flush with top + padding: 0 1.5rem; // This is the container div for the secondary sidebar nav .toc-item { From 98003a7bed8650ecd7b782c5f5b138c2189adf74 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Sat, 20 Dec 2025 15:21:08 -0800 Subject: [PATCH 10/17] Pre-commit fix --- src/sphinx_book_theme/assets/scripts/index.js | 54 +++++++++++-------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/src/sphinx_book_theme/assets/scripts/index.js b/src/sphinx_book_theme/assets/scripts/index.js index cd804828a..256f2a71e 100644 --- a/src/sphinx_book_theme/assets/scripts/index.js +++ b/src/sphinx_book_theme/assets/scripts/index.js @@ -188,19 +188,23 @@ window.toggleFullScreen = toggleFullScreen; 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', + ".theme-switch-button", + ".search-button", + ".primary-toggle", + ".secondary-toggle", ]; // Add blur on click for each button type - buttonSelectors.forEach(selector => { + buttonSelectors.forEach((selector) => { const button = document.querySelector(selector); if (button) { - button.addEventListener('click', () => { - button.blur(); - }, true); + button.addEventListener( + "click", + () => { + button.blur(); + }, + true, + ); } }); } @@ -211,25 +215,29 @@ function addBlurToButtons() { * 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'); + 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 + 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 } } From 410a96ffacbb83b1a9bdfbf3389b4fdab168eb66 Mon Sep 17 00:00:00 2001 From: choldgraf Date: Mon, 22 Dec 2025 09:00:34 -0800 Subject: [PATCH 11/17] Update tests --- tests/test_build/build__header-article.html | 2 +- tests/test_build/header__repo-buttons--all-off.html | 2 +- tests/test_build/header__repo-buttons--all-on.html | 2 +- tests/test_build/header__repo-buttons--custom-branch.html | 2 +- tests/test_build/header__repo-buttons--one-on.html | 2 +- tox.ini | 8 ++++---- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/tests/test_build/build__header-article.html b/tests/test_build/build__header-article.html index 7de4ade05..c33dc832d 100644 --- a/tests/test_build/build__header-article.html +++ b/tests/test_build/build__header-article.html @@ -100,7 +100,7 @@
-
-