MAINT: pin pydata sphinx theme and update regression tests (#862)

* fix: pin pydata-sphinx-theme tests

* feat!: drop sphinx 5 support

* ci: include 8.0

* ci: update action config

* test: fix PST test

* ci: fix matrix

* maint: pin myst-parser test dep

* wip

* chore: drop pyproject pin

* test: add missing regression tests for sphinx 6

* test: catch pending deprecation warning

* fix: ignore warning

* chore: add pyproject.toml to codespell

.github/workflows/tests.yml

@@ -28,11 +28,11 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.9", "3.10", "3.11"]
+        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: ["~=5.0","~=6.0","~=7.0"]
+        sphinx: ["~=6.0","~=7.0", "~=8.0"]
         include:
         - os: windows-latest
           # Python 3.12 is broken on windows builds until the following PR is released:
@@ -42,6 +42,14 @@ jobs:
           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 }}
 
     steps:

.pre-commit-config.yaml

@@ -44,5 +44,6 @@ repos:
         (?x)^(
             docs/reference/kitchen-sink/.*|
             src/sphinx_book_theme/assets/.*|
-            tests/.*
+            tests/.*|
+            pyproject\.toml
         )$

pyproject.toml

@@ -24,6 +24,8 @@ filterwarnings = [
   'ignore:datetime\.datetime\.utcnow\(\) is deprecated:DeprecationWarning',
   # 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'
 ]
 
 [project]
@@ -34,8 +36,8 @@ readme = "README.md"
 
 requires-python = ">=3.9"
 dependencies = [
-  "sphinx>=5",
-  "pydata-sphinx-theme>=0.15.2"
+  "sphinx>=6.1",
+  "pydata-sphinx-theme>=0.16.0"
 ]
 
 license = { file = "LICENSE" }

tests/sites/base/index.rst

@@ -0,0 +1,12 @@
+Index ``with code`` in title
+============================
+
+.. toctree::
+  :caption: My caption
+  :numbered:
+
+  page1
+  page2
+  section1/index
+  titles/index
+  Google <https://google.com>

tests/sites/base/page1.rst

@@ -0,0 +1,14 @@
+Page 1
+======
+
+Test content with Some raw HTML to test.
+
+Section 1
+---------
+
+First section
+
+Section 2
+---------
+
+Second section

tests/sites/base/page2.rst

@@ -0,0 +1,22 @@
+Page 2
+======
+
+Sidenotes
+---------
+
+Some text to test out one sidenote [1]_ and another sidenote [2]_
+
+Marginnotes
+-----------
+
+Some text to test out one marginnote [3]_ and another marginnote [4]_
+
+This is the end of Page 2.
+
+.. [1] This is a sidenote.
+
+.. [2] This is *another* **sidenote**.
+
+.. [3] {-} This is a marginnote.
+
+.. [4] {-} This is *another* **marginnote**.

tests/sites/base/section1/index.rst

@@ -0,0 +1,9 @@
+Section 1 index
+===============
+
+.. toctree::
+  page1
+  ntbk
+  ntbkmd
+  ntbk_octave
+  ntbk_julia

tests/sites/base/section1/page1.rst

@@ -0,0 +1,2 @@
+Section 1 page1
+===============

tests/sites/base/titles/index.rst

@@ -0,0 +1,7 @@
+Testing titles and TOCtree
+==========================
+
+.. toctree::
+   :glob:
+
+   ./*

tests/sites/base/titles/page-multipletitles.rst

@@ -0,0 +1,13 @@
+A page with multiple top-level titles
+=====================================
+
+Some text
+
+A sub-heading
+-------------
+
+Another top-level title
+=======================
+
+Another sub-heading
+-------------------

tests/sites/base/titles/page-onetitle.rst

@@ -0,0 +1,10 @@
+A page with one title and sub-headings
+======================================
+
+Some text
+
+Here’s a sub-heading
+--------------------
+
+Here’s another
+--------------

tests/sites/base/titles/page-onetitlenoheadings.rst

@@ -0,0 +1,4 @@
+A page with a title but no sub-headings
+=======================================
+
+Some text

tests/sites/notitle/index.md → tests/sites/notitle/index.rst

@@ -1,2 +1 @@
-
 This page has no title

tests/test_build/build__header-article.html

@@ -106,22 +106,18 @@
        </i>
       </span>
      </button>
-     <script>
-      document.write(`
-  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
-    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
-    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
-  </button>
-`);
-     </script>
-     <script>
-      document.write(`
-  <button class="btn btn-sm navbar-btn search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
-  </button>
-`);
-     </script>
+     <button aria-label="Color mode" class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" data-bs-placement="bottom" data-bs-title="Color mode" data-bs-toggle="tooltip">
+      <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light">
+      </i>
+      <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark">
+      </i>
+      <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings">
+      </i>
+     </button>
+     <button aria-label="Search" class="btn btn-sm pst-navbar-icon search-button search-button__button pst-js-only" data-bs-placement="bottom" data-bs-toggle="tooltip" title="Search">
+      <i class="fa-solid fa-magnifying-glass fa-lg">
+      </i>
+     </button>
     </div>
    </div>
   </div>

tests/test_build/build__pagetoc--page-multipletitles.html

@@ -1,4 +1,4 @@
-<div class="bd-sidebar-secondary bd-toc">
+<div class="bd-sidebar-secondary bd-toc" id="pst-secondary-sidebar">
  <div class="sidebar-secondary-items sidebar-secondary__inner">
   <div class="sidebar-secondary-item">
    <div class="page-toc tocsection onthispage">

tests/test_build/build__pagetoc--page-onetitle.html

@@ -1,4 +1,4 @@
-<div class="bd-sidebar-secondary bd-toc">
+<div class="bd-sidebar-secondary bd-toc" id="pst-secondary-sidebar">
  <div class="sidebar-secondary-items sidebar-secondary__inner">
   <div class="sidebar-secondary-item">
    <div class="page-toc tocsection onthispage">
@@ -9,12 +9,12 @@
    <nav class="bd-toc-nav page-toc">
     <ul class="visible nav section-nav flex-column">
      <li class="toc-h2 nav-item toc-entry">
-      <a class="reference internal nav-link" href="#here-s-a-sub-heading">
+      <a class="reference internal nav-link" href="#heres-a-sub-heading">
        4.3.1. Here’s a sub-heading
       </a>
      </li>
      <li class="toc-h2 nav-item toc-entry">
-      <a class="reference internal nav-link" href="#here-s-another">
+      <a class="reference internal nav-link" href="#heres-another">
        4.3.2. Here’s another
       </a>
      </li>

tests/test_build/header__repo-buttons--all-off.html

@@ -37,22 +37,18 @@
      </i>
     </span>
    </button>
-   <script>
-    document.write(`
-  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
-    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
-    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
-  </button>
-`);
-   </script>
-   <script>
-    document.write(`
-  <button class="btn btn-sm navbar-btn search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
-  </button>
-`);
-   </script>
+   <button aria-label="Color mode" class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" data-bs-placement="bottom" data-bs-title="Color mode" data-bs-toggle="tooltip">
+    <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light">
+    </i>
+    <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark">
+    </i>
+    <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings">
+    </i>
+   </button>
+   <button aria-label="Search" class="btn btn-sm pst-navbar-icon search-button search-button__button pst-js-only" data-bs-placement="bottom" data-bs-toggle="tooltip" title="Search">
+    <i class="fa-solid fa-magnifying-glass fa-lg">
+    </i>
+   </button>
   </div>
  </div>
 </div>

tests/test_build/header__repo-buttons--all-on.html

@@ -78,22 +78,18 @@
      </i>
     </span>
    </button>
-   <script>
-    document.write(`
-  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
-    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
-    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
-  </button>
-`);
-   </script>
-   <script>
-    document.write(`
-  <button class="btn btn-sm navbar-btn search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
-    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
-  </button>
-`);
-   </script>
+   <button aria-label="Color mode" class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" data-bs-placement="bottom" data-bs-title="Color mode" data-bs-toggle="tooltip">
+    <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light">
+    </i>
+    <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark">
+    </i>
+    <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings">
+    </i>
+   </button>
+   <button aria-label="Search" class="btn btn-sm pst-navbar-icon search-button search-button__button pst-js-only" data-bs-placement="bottom" data-bs-toggle="tooltip" title="Search">
+    <i class="fa-solid fa-magnifying-glass fa-lg">
+    </i>
+   </button>
   </div>
  </div>
 </div>