From c1cfeaa4ffdc34303bba5cfc592f24aa83137f8c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 12:08:57 +0000
Subject: [PATCH 01/73] Add python default doc

---
 .python-version-default | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 .python-version-default

diff --git a/.python-version-default b/.python-version-default
new file mode 100644
index 000000000..fdcfcfdfc
--- /dev/null
+++ b/.python-version-default
@@ -0,0 +1 @@
+3.12
\ No newline at end of file

From 1edcade95fa5cda34250ac6b9689e4f808362e99 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 12:09:50 +0000
Subject: [PATCH 02/73] Add tox configuration

---
 pyproject.toml |  2 +-
 tox.ini        | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 tox.ini

diff --git a/pyproject.toml b/pyproject.toml
index 8d674125d..f2a15ac81 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -78,7 +78,7 @@ doc = [
   "colorama",
 ]
 test = ["pytest", "pytest-cov", "pytest-regressions"]
-dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]"]
+dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox"]
 a11y = ["pytest-playwright"]
 
 [project.entry-points]
diff --git a/tox.ini b/tox.ini
new file mode 100644
index 000000000..bd2219d39
--- /dev/null
+++ b/tox.ini
@@ -0,0 +1,48 @@
+[tox]
+min_version = 4
+env_list =
+    pre-commit,
+    py3{9,12},
+    a11y,
+    docs
+
+[testenv:pre-commit]
+skip_install = true
+deps = pre-commit
+commands = pre-commit run --all-files
+
+[testenv:py3{9,12}]
+description = run tests across Python versions between 3.9 and 3.12
+extras =
+    # install testing dependencies - defined in pyproject.toml
+    testing
+commands = 
+    pytest -m "not a11y" {posargs}
+
+# tox run -e a11y
+[testenv:a11y]
+description = run accessibility tests with Playwright and axe-core
+base_python = py312
+extras = 
+    # install testing dependencies - defined in pyproject.toml
+    testing
+    accessibility
+allowlist_externals=playwright
+depends = docs
+; commands_pre =
+    # install Playwright dependencies
+commands = 
+    playwright install
+    pytest -m "a11y" {posargs}
+
+# tox run -e docs
+[testenv:docs]
+description = build the documentation and place in docs/_build/html. Use --no-compile to skip compilation
+base_python = py312
+# suppress Py3.11's new "can't debug frozen modules" warning
+set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
+extras = 
+    docs: doc
+commands =
+    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
+    python tests/utils/check_warnings.py

From d71c46acf434517e451c8a828dab997d67e2a88c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 12:35:07 +0000
Subject: [PATCH 03/73] Add tox based workflow

---
 .github/workflows/tests_tox.yml | 69 +++++++++++++++++++++++++++++++++
 tox.ini                         |  7 ++++
 2 files changed, 76 insertions(+)
 create mode 100644 .github/workflows/tests_tox.yml

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
new file mode 100644
index 000000000..7c53c0e84
--- /dev/null
+++ b/.github/workflows/tests_tox.yml
@@ -0,0 +1,69 @@
+name: continuous-integration
+
+# Concurrency group that uses the workflow name and PR number if available
+# or commit SHA as a fallback. If a new build is triggered under that
+# concurrency group while a previous build is running it will be canceled.
+# Repeated pushes to a PR will cancel all previous builds, while multiple
+# merges to main will not cancel.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1" # Make tools pretty
+  PYTHONUNBUFFERED: "1" # Make stdout and stderr behave well
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_call:
+  # allow manual triggering of the workflow, while debugging
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup Python 🐍"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version-default
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
+      - name: "Run pre-commit 🔍"
+        uses: pre-commit/action@v3.0.0
+
+  # run our test suite on various combinations of OS / Python / Sphinx version
+  run-pytest:
+    needs: lint
+    strategy:
+      # while debugging, set fail-fast to false
+      fail-fast: true
+      matrix:
+        # os: [ubuntu-latest, windows-latest, macos-latest]
+        os: [ubuntu-latest]
+        python-version: [3.9, 3.10., 3.11, 3.12]
+        sphinx-version: ["dev", "6.1.0"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup Python 🐍"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: "pyproject.toml"
+      - run: python -Im pip install tox-uv
+        # waiting for https://github.com/nikeee/setup-pandoc/pull/8
+        # using 12rambau fork until then
+      - name: "Install pandoc 📝"
+        uses: 12rambau/setup-pandoc@test
+      - name: "Run tests"
+        run: |
+          # get the python version from the matrix and substitute
+          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
diff --git a/tox.ini b/tox.ini
index bd2219d39..f09d6729b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -46,3 +46,10 @@ extras =
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
+
+
+[testenv:compile-i18n]
+description = compile the MO files required for internationalization
+deps = sphinx-theme-builder[cli]
+command =
+    stb compile

From 03c8531e1d4b8ac0fe177324b9470772115eaed1 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 12:35:46 +0000
Subject: [PATCH 04/73] Rename workflow

---
 .github/workflows/tests_tox.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 7c53c0e84..8fe89c400 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -1,4 +1,4 @@
-name: continuous-integration
+name: continuous-integration-tox
 
 # Concurrency group that uses the workflow name and PR number if available
 # or commit SHA as a fallback. If a new build is triggered under that

From a992b12b5a0125b6101580ae91f5961152acc628 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 12:37:17 +0000
Subject: [PATCH 05/73] Add debugging branch

---
 .github/workflows/tests_tox.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 8fe89c400..3bac36a34 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -17,6 +17,7 @@ on:
   push:
     branches:
       - main
+      - trallard/* # allow for personal branches for debugging
   pull_request:
   workflow_call:
   # allow manual triggering of the workflow, while debugging

From 72bec4b1d1c01b206f7256aafff767d963051ccc Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 12:43:06 +0000
Subject: [PATCH 06/73] Remove extra .

---
 .github/workflows/tests_tox.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 3bac36a34..aeb9ad0a7 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -13,6 +13,8 @@ env:
   FORCE_COLOR: "1" # Make tools pretty
   PYTHONUNBUFFERED: "1" # Make stdout and stderr behave well
 
+permissions: {}
+
 on:
   push:
     branches:
@@ -47,7 +49,7 @@ jobs:
       matrix:
         # os: [ubuntu-latest, windows-latest, macos-latest]
         os: [ubuntu-latest]
-        python-version: [3.9, 3.10., 3.11, 3.12]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
         sphinx-version: ["dev", "6.1.0"]
     runs-on: ${{ matrix.os }}
     steps:

From a1baedc0eded15dcbab0577378ddb0f86e21e1b4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 15:17:04 +0000
Subject: [PATCH 07/73] Update tox commands

---
 .github/workflows/tests_tox.yml |  4 +---
 tox.ini                         | 28 ++++++++++++++++------------
 2 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index aeb9ad0a7..8e0828b31 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -11,7 +11,6 @@ concurrency:
 
 env:
   FORCE_COLOR: "1" # Make tools pretty
-  PYTHONUNBUFFERED: "1" # Make stdout and stderr behave well
 
 permissions: {}
 
@@ -68,5 +67,4 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          # get the python version from the matrix and substitute
-          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+          # python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
diff --git a/tox.ini b/tox.ini
index f09d6729b..5942be272 100644
--- a/tox.ini
+++ b/tox.ini
@@ -11,28 +11,31 @@ skip_install = true
 deps = pre-commit
 commands = pre-commit run --all-files
 
-[testenv:py3{9,12}]
+[testenv:py3{9,10,11,12}]
 description = run tests across Python versions between 3.9 and 3.12
+# need to ensure the package is installed in editable mode
+package = editable
 extras =
-    # install testing dependencies - defined in pyproject.toml
-    testing
+    # install dependencies - defined in pyproject.toml
+    test
+# need to run compile-i18n first to ensure MO files are up-to-date
+deps = sphinx-theme-builder[cli]
 commands = 
-    pytest -m "not a11y" {posargs}
+    stb compile
+    pytest -m "not a11y"
 
 # tox run -e a11y
 [testenv:a11y]
 description = run accessibility tests with Playwright and axe-core
 base_python = py312
 extras = 
-    # install testing dependencies - defined in pyproject.toml
-    testing
-    accessibility
+    # install dependencies - defined in pyproject.toml
+    test
+    a11y
 allowlist_externals=playwright
 depends = docs
-; commands_pre =
-    # install Playwright dependencies
 commands = 
-    playwright install
+    playwright install 
     pytest -m "a11y" {posargs}
 
 # tox run -e docs
@@ -42,12 +45,13 @@ base_python = py312
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = 
-    docs: doc
+    # install dependencies - defined in pyproject.toml
+    doc
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
 
-
+# tox run -e compile-i18n
 [testenv:compile-i18n]
 description = compile the MO files required for internationalization
 deps = sphinx-theme-builder[cli]

From 027c2bb8f476700d26ecac30691c729af1a0a8ca Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 15:52:18 +0000
Subject: [PATCH 08/73] Add sphinx versions test

---
 .github/workflows/tests_tox.yml | 40 +++++++++++++++++++++++++++++----
 tox.ini                         |  8 +++++--
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 8e0828b31..d4c07159c 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -46,10 +46,8 @@ jobs:
       # while debugging, set fail-fast to false
       fail-fast: true
       matrix:
-        # os: [ubuntu-latest, windows-latest, macos-latest]
-        os: [ubuntu-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
-        sphinx-version: ["dev", "6.1.0"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"
@@ -67,4 +65,38 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          # python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+
+  run-tests:
+    needs: lint
+    strategy:
+      # while debugging, set fail-fast to false
+      fail-fast: true
+      matrix:
+        python-version: ["3.9", "3.12"]
+        sphinx-version: [61, dev]
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup Python 🐍"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: "pyproject.toml"
+      - run: python -Im pip install tox-uv
+        # waiting for https://github.com/nikeee/setup-pandoc/pull/8
+        # using 12rambau fork until then
+      - name: "Install pandoc 📝"
+        uses: 12rambau/setup-pandoc@test
+        # oldest python version with the oldest sphinx version
+      - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
+        run: |
+          python -Im tox run py39-sphinx61
+        if: matrix.sphinx-version == 61 && matrix.python-version == "3.9"
+        # newest python version with the newest sphinx version
+      - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
+        run: |
+          python -Im tox run py39-sphinx61
+        if: matrix.sphinx-version == dev && matrix.python-version == "3.12"
diff --git a/tox.ini b/tox.ini
index 5942be272..f459049e2 100644
--- a/tox.ini
+++ b/tox.ini
@@ -11,7 +11,7 @@ skip_install = true
 deps = pre-commit
 commands = pre-commit run --all-files
 
-[testenv:py3{9,10,11,12}]
+[testenv:py3{9,10,11,12}-sphinx{61,dev}]
 description = run tests across Python versions between 3.9 and 3.12
 # need to ensure the package is installed in editable mode
 package = editable
@@ -19,11 +19,15 @@ extras =
     # install dependencies - defined in pyproject.toml
     test
 # need to run compile-i18n first to ensure MO files are up-to-date
-deps = sphinx-theme-builder[cli]
+deps = 
+    sphinx-theme-builder[cli]
+    py39-sphinx61: sphinx==6.1.0
+    py312-sphinxdev: sphinx @ git+https://github.com/sphinx-doc/sphinx.git@master
 commands = 
     stb compile
     pytest -m "not a11y"
 
+
 # tox run -e a11y
 [testenv:a11y]
 description = run accessibility tests with Playwright and axe-core

From 5a282dad216907925e6498cfb39ce1a303a07004 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 15:58:45 +0000
Subject: [PATCH 09/73] Update workflow syntax

---
 .github/workflows/tests_tox.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index d4c07159c..0dc8ae69d 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -92,11 +92,11 @@ jobs:
         uses: 12rambau/setup-pandoc@test
         # oldest python version with the oldest sphinx version
       - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
+        if: ${{ matrix.sphinx-version }} == 61 && ${{ matrix.python-version }} == "3.9"
         run: |
           python -Im tox run py39-sphinx61
-        if: matrix.sphinx-version == 61 && matrix.python-version == "3.9"
         # newest python version with the newest sphinx version
       - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
+        if: ${{ matrix.sphinx-version}} == dev && ${{matrix.python-version}} == "3.12"
         run: |
           python -Im tox run py39-sphinx61
-        if: matrix.sphinx-version == dev && matrix.python-version == "3.12"

From d285c4d6c3763b200abdd45a2ec2d43539f59b12 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 16:23:02 +0000
Subject: [PATCH 10/73] Fix typo

---
 .github/workflows/tests_tox.yml | 22 ++++++++++++++++++++--
 tox.ini                         |  1 -
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 0dc8ae69d..abbbf8069 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -94,9 +94,27 @@ jobs:
       - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
         if: ${{ matrix.sphinx-version }} == 61 && ${{ matrix.python-version }} == "3.9"
         run: |
-          python -Im tox run py39-sphinx61
+          python -Im tox run -e py39-sphinx61
         # newest python version with the newest sphinx version
       - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
         if: ${{ matrix.sphinx-version}} == dev && ${{matrix.python-version}} == "3.12"
         run: |
-          python -Im tox run py39-sphinx61
+          python -Im tox run -e py312-sphinxdev
+
+  a11y-tests:
+    needs: lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup Python 🐍"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version-default
+          cache: pip
+          cache-dependency-path: "pyproject.toml"
+      - run: python -Im pip install tox-uv
+      - name: "Run accessibility tests with playwright 🎭"
+        run: python -Im tox run -e a11y
+        continue-on-error: true
diff --git a/tox.ini b/tox.ini
index f459049e2..4367b5c1c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -37,7 +37,6 @@ extras =
     test
     a11y
 allowlist_externals=playwright
-depends = docs
 commands = 
     playwright install 
     pytest -m "a11y" {posargs}

From c90409b5bbbe1b631375398b6535c640796c5931 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 28 Mar 2024 16:37:45 +0000
Subject: [PATCH 11/73] Add build docs

---
 .github/workflows/tests_tox.yml | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index abbbf8069..3d19a1c05 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -39,11 +39,10 @@ jobs:
       - name: "Run pre-commit 🔍"
         uses: pre-commit/action@v3.0.0
 
-  # run our test suite on various combinations of OS / Python / Sphinx version
+  # run our test suite on various combinations of OS / Python version
   run-pytest:
     needs: lint
     strategy:
-      # while debugging, set fail-fast to false
       fail-fast: true
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
@@ -118,3 +117,24 @@ jobs:
       - name: "Run accessibility tests with playwright 🎭"
         run: python -Im tox run -e a11y
         continue-on-error: true
+
+  build-site:
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup Python 🐍"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version-default
+          cache: pip
+          cache-dependency-path: "pyproject.toml"
+      - run: python -Im pip install tox-uv
+      - name: "Build docs and check for warnings"
+        run: python -Im tox run -e docs

From 5da34828d76433a61e3e36a899fcdb3c8c47b8d0 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 12:27:43 +0100
Subject: [PATCH 12/73] Add pandoc

---
 .github/workflows/tests_tox.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 3d19a1c05..cd6750b02 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -45,7 +45,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
     runs-on: ${{ matrix.os }}
     steps:
@@ -135,6 +135,8 @@ jobs:
           python-version-file: .python-version-default
           cache: pip
           cache-dependency-path: "pyproject.toml"
+      - name: "Install pandoc 📝"
+        uses: 12rambau/setup-pandoc@test
       - run: python -Im pip install tox-uv
       - name: "Build docs and check for warnings"
         run: python -Im tox run -e docs

From 3280ac08e134acde71d15d40a9c062d7b9b3f28a Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 16:02:41 +0100
Subject: [PATCH 13/73] Exclude non-supported version

---
 .github/workflows/tests_tox.yml | 55 +++++++++++----------------------
 tox.ini                         |  9 +++---
 2 files changed, 23 insertions(+), 41 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index cd6750b02..ae3cdba9f 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -47,6 +47,19 @@ jobs:
       matrix:
         os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
+        include:
+          # oldest Python version with the oldest Sphinx version
+          - os: ubuntu-latest
+            python-version: "3.9"
+            sphinx-version: "6.1"
+            # newest Python version with the newest Sphinx version
+          - os: ubuntu-latest
+            python-version: "3.12"
+            sphinx-version: "dev"
+        exclude:
+          # Python 3.9 is not supported on macOS 14 - https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json
+          - os: macos-14
+            python-version: "3.9"
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"
@@ -64,46 +77,15 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
-
-  run-tests:
-    needs: lint
-    strategy:
-      # while debugging, set fail-fast to false
-      fail-fast: true
-      matrix:
-        python-version: ["3.9", "3.12"]
-        sphinx-version: [61, dev]
-    runs-on: ubuntu-latest
-    steps:
-      - name: "Checkout repository 🛎"
-        uses: actions/checkout@v4
-      - name: "Setup Python 🐍"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
-          cache-dependency-path: "pyproject.toml"
-      - run: python -Im pip install tox-uv
-        # waiting for https://github.com/nikeee/setup-pandoc/pull/8
-        # using 12rambau fork until then
-      - name: "Install pandoc 📝"
-        uses: 12rambau/setup-pandoc@test
-        # oldest python version with the oldest sphinx version
-      - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
-        if: ${{ matrix.sphinx-version }} == 61 && ${{ matrix.python-version }} == "3.9"
-        run: |
-          python -Im tox run -e py39-sphinx61
-        # newest python version with the newest sphinx version
-      - name: "${{ matrix.python-version }} - ${{ matrix.sphinx-version }}"
-        if: ${{ matrix.sphinx-version}} == dev && ${{matrix.python-version}} == "3.12"
-        run: |
-          python -Im tox run -e py312-sphinxdev
+          if [[ -z ${{ matrix.sphinx-version }} ]]; then
+            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)
+          else
+            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+          fi
 
   a11y-tests:
     needs: lint
     runs-on: ubuntu-latest
-
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
@@ -125,7 +107,6 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
-
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
diff --git a/tox.ini b/tox.ini
index 4367b5c1c..e0f22831a 100644
--- a/tox.ini
+++ b/tox.ini
@@ -2,9 +2,10 @@
 min_version = 4
 env_list =
     pre-commit,
-    py3{9,12},
+    py3{9,10,11,12}-sphinx{61,dev},
     a11y,
-    docs
+    docs,
+    compile-i18n
 
 [testenv:pre-commit]
 skip_install = true
@@ -12,7 +13,7 @@ deps = pre-commit
 commands = pre-commit run --all-files
 
 [testenv:py3{9,10,11,12}-sphinx{61,dev}]
-description = run tests across Python versions between 3.9 and 3.12
+description = run tests across Python versions between 3.9 and 3.12, if a sphinx version is specified it will use that version vs the default in pyproject.toml
 # need to ensure the package is installed in editable mode
 package = editable
 extras =
@@ -22,7 +23,7 @@ extras =
 deps = 
     sphinx-theme-builder[cli]
     py39-sphinx61: sphinx==6.1.0
-    py312-sphinxdev: sphinx @ git+https://github.com/sphinx-doc/sphinx.git@master
+    py312-sphinxdev: sphinx @ git+https://github.com/sphinx-doc/sphinx.git@master[dev]
 commands = 
     stb compile
     pytest -m "not a11y"

From cf30a7fb075f4c9d47caf236c3b210bdad16c31c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 16:23:01 +0100
Subject: [PATCH 14/73] Remove if check

---
 .github/workflows/tests_tox.yml | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index ae3cdba9f..82736e9da 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -47,6 +47,7 @@ jobs:
       matrix:
         os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
+        sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
@@ -77,11 +78,7 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          if [[ -z ${{ matrix.sphinx-version }} ]]; then
-            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)
-          else
-            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
-          fi
+          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)
 
   a11y-tests:
     needs: lint

From d9c18fb801173463ddf854efa8fa685f0538ec4b Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 16:30:00 +0100
Subject: [PATCH 15/73] Fix sphinx version expression

---
 .github/workflows/tests_tox.yml | 4 ++--
 tox.ini                         | 5 +++++
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 82736e9da..de1f9e065 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -52,7 +52,7 @@ jobs:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: "6.1"
+            sphinx-version: "61"
             # newest Python version with the newest Sphinx version
           - os: ubuntu-latest
             python-version: "3.12"
@@ -78,7 +78,7 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)
+          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }})
 
   a11y-tests:
     needs: lint
diff --git a/tox.ini b/tox.ini
index e0f22831a..a2ebbc468 100644
--- a/tox.ini
+++ b/tox.ini
@@ -61,3 +61,8 @@ description = compile the MO files required for internationalization
 deps = sphinx-theme-builder[cli]
 command =
     stb compile
+
+[testenv:lint]
+description = run linting checks
+deps = pre-commit
+commands = pre-commit run -a
\ No newline at end of file

From 47fc9674de110505c127b5a0ca1f058d58ea36d7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 16:38:32 +0100
Subject: [PATCH 16/73] Use composite action

---
 .github/actions/set-dev-env/action.yml | 20 ++++++++++++++++++++
 .github/workflows/tests_tox.yml        | 11 ++++-------
 2 files changed, 24 insertions(+), 7 deletions(-)
 create mode 100644 .github/actions/set-dev-env/action.yml

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
new file mode 100644
index 000000000..c3459e0c8
--- /dev/null
+++ b/.github/actions/set-dev-env/action.yml
@@ -0,0 +1,20 @@
+name: Setup PST CI environment
+description: Create a PST dev environment
+
+inputs:
+  python-version:
+    description: Python version to use
+    required: false
+    default: "3.12"
+
+runs:
+  using: composite
+  steps:
+    - name: "Setup Python 🐍"
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ python-version }}
+        cache: "pip"
+        cache-dependency-path: "pyproject.toml"
+    - run: python -Im pip install tox-uv
+      shell: bash
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index de1f9e065..555a75a88 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -78,7 +78,7 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }})
+          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
 
   a11y-tests:
     needs: lint
@@ -86,13 +86,10 @@ jobs:
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
-      - name: "Setup Python 🐍"
-        uses: actions/setup-python@v5
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
         with:
-          python-version-file: .python-version-default
-          cache: pip
-          cache-dependency-path: "pyproject.toml"
-      - run: python -Im pip install tox-uv
+          python-version: "3.12"
       - name: "Run accessibility tests with playwright 🎭"
         run: python -Im tox run -e a11y
         continue-on-error: true

From cfbfe6001101766321d5e5e36355dff6257665ae Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 16:44:21 +0100
Subject: [PATCH 17/73] Fix inputs in composite

---
 .github/actions/set-dev-env/action.yml | 2 +-
 .github/workflows/tests_tox.yml        | 7 +++++--
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index c3459e0c8..4be24a9e2 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -13,7 +13,7 @@ runs:
     - name: "Setup Python 🐍"
       uses: actions/setup-python@v5
       with:
-        python-version: ${{ python-version }}
+        python-version: ${{ inputs.python-version }}
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
     - run: python -Im pip install tox-uv
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 555a75a88..15ffa67b7 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -78,8 +78,11 @@ jobs:
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
         run: |
-          python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
-
+          if [ -n "${{matrix.sphinx-version}}" ]; then
+            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
+          else
+            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+          fi
   a11y-tests:
     needs: lint
     runs-on: ubuntu-latest

From 84c554c49a72dff19fd126e3bcfdda79a0420190 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 16:59:12 +0100
Subject: [PATCH 18/73] Install Sphinx dev deps

---
 .github/actions/set-dev-env/action.yml | 1 +
 tox.ini                                | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 4be24a9e2..749cd0c35 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -12,6 +12,7 @@ runs:
   steps:
     - name: "Setup Python 🐍"
       uses: actions/setup-python@v5
+      if: ${{ inputs.python-version }}
       with:
         python-version: ${{ inputs.python-version }}
         cache: "pip"
diff --git a/tox.ini b/tox.ini
index a2ebbc468..e20faa886 100644
--- a/tox.ini
+++ b/tox.ini
@@ -23,7 +23,7 @@ extras =
 deps = 
     sphinx-theme-builder[cli]
     py39-sphinx61: sphinx==6.1.0
-    py312-sphinxdev: sphinx @ git+https://github.com/sphinx-doc/sphinx.git@master[dev]
+    py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 commands = 
     stb compile
     pytest -m "not a11y"

From 4272ccc68bdb4a5c95d79f2e26c3c7cd0c97adc8 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 17:30:42 +0100
Subject: [PATCH 19/73] Always use bash

---
 .github/workflows/tests_tox.yml | 16 ++++++++--------
 tox.ini                         |  3 ++-
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 15ffa67b7..79807a7e7 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -11,6 +11,7 @@ concurrency:
 
 env:
   FORCE_COLOR: "1" # Make tools pretty
+  DEFAULT_PYTHON_VERSION: "3.12" # Default Python version to use
 
 permissions: {}
 
@@ -30,14 +31,12 @@ jobs:
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
-      - name: "Setup Python 🐍"
-        uses: actions/setup-python@v5
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
         with:
-          python-version-file: .python-version-default
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - name: "Run pre-commit 🔍"
-        uses: pre-commit/action@v3.0.0
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+      - name: "Run lint checks 🧹"
+        run: python -Im tox run -e lint
 
   # run our test suite on various combinations of OS / Python version
   run-pytest:
@@ -77,6 +76,7 @@ jobs:
       - name: "Install pandoc 📝"
         uses: 12rambau/setup-pandoc@test
       - name: "Run tests"
+        shell: bash
         run: |
           if [ -n "${{matrix.sphinx-version}}" ]; then
             python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
@@ -92,7 +92,7 @@ jobs:
       - name: "Setup CI environment 🛠"
         uses: ./.github/actions/set-dev-env
         with:
-          python-version: "3.12"
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Run accessibility tests with playwright 🎭"
         run: python -Im tox run -e a11y
         continue-on-error: true
diff --git a/tox.ini b/tox.ini
index e20faa886..ae754a791 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,7 +5,8 @@ env_list =
     py3{9,10,11,12}-sphinx{61,dev},
     a11y,
     docs,
-    compile-i18n
+    compile-i18n,
+    lint
 
 [testenv:pre-commit]
 skip_install = true

From 3f3b203a5156a030d7211f7cabb5dbf36ffc08b5 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 18:30:34 +0100
Subject: [PATCH 20/73] Add lighthouse audits

---
 .github/actions/set-dev-env/action.yml | 10 +++++
 .github/workflows/tests_tox.yml        | 57 ++++++++++++++++++--------
 .python-version-default                |  1 -
 tox.ini                                | 21 ++++++++++
 4 files changed, 71 insertions(+), 18 deletions(-)
 delete mode 100644 .python-version-default

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 749cd0c35..c656b5569 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -6,6 +6,10 @@ inputs:
     description: Python version to use
     required: false
     default: "3.12"
+  pandoc:
+    description: Whether this should install pandoc or not
+    required: false
+    default: "False"
 
 runs:
   using: composite
@@ -19,3 +23,9 @@ runs:
         cache-dependency-path: "pyproject.toml"
     - run: python -Im pip install tox-uv
       shell: bash
+    # waiting for https://github.com/nikeee/setup-pandoc/pull/8
+    # using 12rambau fork until then
+    - name: "Install pandoc 📝"
+      shell: bash
+      if: ${{ inputs.pandoc }} == "True"
+      uses: 12rambau/setup-pandoc@test
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 79807a7e7..c58bf97f4 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -64,17 +64,11 @@ jobs:
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
-      - name: "Setup Python 🐍"
-        uses: actions/setup-python@v5
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
-          cache-dependency-path: "pyproject.toml"
-      - run: python -Im pip install tox-uv
-        # waiting for https://github.com/nikeee/setup-pandoc/pull/8
-        # using 12rambau fork until then
-      - name: "Install pandoc 📝"
-        uses: 12rambau/setup-pandoc@test
+          pandoc: "True"
       - name: "Run tests"
         shell: bash
         run: |
@@ -83,6 +77,8 @@ jobs:
           else
             python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
           fi
+
+  # Only run accessibility tests on the latest Python version (3.12) and Ubuntu
   a11y-tests:
     needs: lint
     runs-on: ubuntu-latest
@@ -97,6 +93,7 @@ jobs:
         run: python -Im tox run -e a11y
         continue-on-error: true
 
+  # Build sites on the 2 major OSes and check for warnings
   build-site:
     needs: lint
     strategy:
@@ -107,14 +104,40 @@ jobs:
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
-      - name: "Setup Python 🐍"
-        uses: actions/setup-python@v5
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
         with:
-          python-version-file: .python-version-default
-          cache: pip
-          cache-dependency-path: "pyproject.toml"
-      - name: "Install pandoc 📝"
-        uses: 12rambau/setup-pandoc@test
-      - run: python -Im pip install tox-uv
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+          pandoc: "True"
       - name: "Build docs and check for warnings"
         run: python -Im tox run -e docs
+
+  # Run Lighthouse audits on the built site (Ubuntu)
+  lighthouse-audit:
+    needs: build-site
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+      - name: "Run Lighthouse audits on the built site"
+        run: python -Im tox run -e lighthouse
+      - name: "Copy kitchen sink to a tiny site"
+        run: |
+          mkdir audit/
+          mkdir audit/site
+          cp -r docs/examples/kitchen-sink audit/site/kitchen-sink
+          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > audit/site/index.rst
+          echo 'html_theme = "pydata_sphinx_theme"' > audit/site/conf.py
+          echo '.. toctree::\n   :glob:\n\n   *' >> audit/site/index.rst
+          python -Im tox run -e docs-no-checks
+      - name: "Audit with Lighthouse 🔦"
+        uses: treosh/lighthouse-ci-action@v11
+        with:
+          configPath: ".github/workflows/lighthouserc.json"
+          temporaryPublicStorage: true
+          uploadArtifacts: true
+          runs: 3 # Multiple runs to reduce variance
diff --git a/.python-version-default b/.python-version-default
deleted file mode 100644
index fdcfcfdfc..000000000
--- a/.python-version-default
+++ /dev/null
@@ -1 +0,0 @@
-3.12
\ No newline at end of file
diff --git a/tox.ini b/tox.ini
index ae754a791..801bea711 100644
--- a/tox.ini
+++ b/tox.ini
@@ -56,6 +56,26 @@ commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
 
+# tox run -e docs
+[testenv:docs]
+description = build the documentation and place in docs/_build/html, then check
+for warnings
+base_python = py312
+# suppress Py3.11's new "can't debug frozen modules" warning
+set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
+extras = 
+    # install dependencies - defined in pyproject.toml
+    doc
+commands =
+    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
+    python tests/utils/check_warnings.py
+
+[testenv:docs-no-checks]
+description = build the documentations without checking for warnings
+base_python = {[testenv:docs]base_python}
+extras = {[testenv:docs]extras}
+commands = sphinx-build audit/site audit/_build {posargs}
+
 # tox run -e compile-i18n
 [testenv:compile-i18n]
 description = compile the MO files required for internationalization
@@ -65,5 +85,6 @@ command =
 
 [testenv:lint]
 description = run linting checks
+base_python = py312
 deps = pre-commit
 commands = pre-commit run -a
\ No newline at end of file

From 0c36b2e68f2380c219f511bc01b37d561d137794 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 19:11:46 +0100
Subject: [PATCH 21/73] Allow for build docs params

---
 .github/actions/set-dev-env/action.yml |  4 +--
 .github/workflows/tests_tox.yml        | 16 ++++++++++--
 tox.ini                                | 34 +++++++++-----------------
 3 files changed, 26 insertions(+), 28 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index c656b5569..2e6851e3a 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -16,7 +16,6 @@ runs:
   steps:
     - name: "Setup Python 🐍"
       uses: actions/setup-python@v5
-      if: ${{ inputs.python-version }}
       with:
         python-version: ${{ inputs.python-version }}
         cache: "pip"
@@ -26,6 +25,5 @@ runs:
     # waiting for https://github.com/nikeee/setup-pandoc/pull/8
     # using 12rambau fork until then
     - name: "Install pandoc 📝"
-      shell: bash
-      if: ${{ inputs.pandoc }} == "True"
       uses: 12rambau/setup-pandoc@test
+      if: ${{ inputs.pandoc }} == "True"
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index c58bf97f4..724a0dd38 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -12,6 +12,7 @@ concurrency:
 env:
   FORCE_COLOR: "1" # Make tools pretty
   DEFAULT_PYTHON_VERSION: "3.12" # Default Python version to use
+  OLDEST_SPHINX_VERSION: "61" # Oldest Sphinx version to test, without .
 
 permissions: {}
 
@@ -51,7 +52,7 @@ jobs:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: "61"
+            sphinx-version: ${{ env.OLDEST_SPHINX_VERSION }}
             # newest Python version with the newest Sphinx version
           - os: ubuntu-latest
             python-version: "3.12"
@@ -100,6 +101,12 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12"]
+        sphinx-version: [""]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.9"
+            sphinx-version: ${{ env.OLDEST_SPHINX_VERSION }}
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"
@@ -107,10 +114,15 @@ jobs:
       - name: "Setup CI environment 🛠"
         uses: ./.github/actions/set-dev-env
         with:
-          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+          python-version: ${{ matrix.python-version }}
           pandoc: "True"
       - name: "Build docs and check for warnings"
         run: python -Im tox run -e docs
+          if [ -n "${{matrix.sphinx-version}}" ]; then
+          python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
+          else
+          python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)
+          fi
 
   # Run Lighthouse audits on the built site (Ubuntu)
   lighthouse-audit:
diff --git a/tox.ini b/tox.ini
index 801bea711..b1721f017 100644
--- a/tox.ini
+++ b/tox.ini
@@ -4,8 +4,8 @@ env_list =
     pre-commit,
     py3{9,10,11,12}-sphinx{61,dev},
     a11y,
-    docs,
-    compile-i18n,
+    docs-py3{9,12}-sphinx{61},
+    compile,
     lint
 
 [testenv:pre-commit]
@@ -20,7 +20,7 @@ package = editable
 extras =
     # install dependencies - defined in pyproject.toml
     test
-# need to run compile-i18n first to ensure MO files are up-to-date
+# need to run compile first to ensure MO files are up-to-date
 deps = 
     sphinx-theme-builder[cli]
     py39-sphinx61: sphinx==6.1.0
@@ -44,28 +44,16 @@ commands =
     pytest -m "a11y" {posargs}
 
 # tox run -e docs
-[testenv:docs]
-description = build the documentation and place in docs/_build/html. Use --no-compile to skip compilation
-base_python = py312
-# suppress Py3.11's new "can't debug frozen modules" warning
-set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
-extras = 
-    # install dependencies - defined in pyproject.toml
-    doc
-commands =
-    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
-    python tests/utils/check_warnings.py
-
-# tox run -e docs
-[testenv:docs]
-description = build the documentation and place in docs/_build/html, then check
-for warnings
+[testenv:docs-py3{9,12}-sphinx{61}]
+description = build the documentation and place in docs/_build/html
 base_python = py312
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = 
     # install dependencies - defined in pyproject.toml
     doc
+deps = 
+    py39-sphinx61: sphinx==6.1.0
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
@@ -76,9 +64,9 @@ base_python = {[testenv:docs]base_python}
 extras = {[testenv:docs]extras}
 commands = sphinx-build audit/site audit/_build {posargs}
 
-# tox run -e compile-i18n
-[testenv:compile-i18n]
-description = compile the MO files required for internationalization
+# tox run -e compile
+[testenv:compile]
+description = "compile the theme's web assets with sphinx-theme-builder"
 deps = sphinx-theme-builder[cli]
 command =
     stb compile
@@ -87,4 +75,4 @@ command =
 description = run linting checks
 base_python = py312
 deps = pre-commit
-commands = pre-commit run -a
\ No newline at end of file
+commands = pre-commit run -a

From b3ce8b3c9f5f59808f4d41589268f95311563ee7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 19:17:53 +0100
Subject: [PATCH 22/73] Fix deps - docs

---
 .github/actions/set-dev-env/action.yml | 2 +-
 .github/workflows/tests_tox.yml        | 5 ++---
 tox.ini                                | 6 +++---
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 2e6851e3a..0cf559f1e 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -26,4 +26,4 @@ runs:
     # using 12rambau fork until then
     - name: "Install pandoc 📝"
       uses: 12rambau/setup-pandoc@test
-      if: ${{ inputs.pandoc }} == "True"
+      if: ${{ inputs.pandoc == "True" }}
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 724a0dd38..05a69159c 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -12,7 +12,6 @@ concurrency:
 env:
   FORCE_COLOR: "1" # Make tools pretty
   DEFAULT_PYTHON_VERSION: "3.12" # Default Python version to use
-  OLDEST_SPHINX_VERSION: "61" # Oldest Sphinx version to test, without .
 
 permissions: {}
 
@@ -52,7 +51,7 @@ jobs:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: ${{ env.OLDEST_SPHINX_VERSION }}
+            sphinx-version: "61"
             # newest Python version with the newest Sphinx version
           - os: ubuntu-latest
             python-version: "3.12"
@@ -106,7 +105,7 @@ jobs:
         include:
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: ${{ env.OLDEST_SPHINX_VERSION }}
+            sphinx-version: "61"
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"
diff --git a/tox.ini b/tox.ini
index b1721f017..4b31f1ed4 100644
--- a/tox.ini
+++ b/tox.ini
@@ -20,7 +20,7 @@ package = editable
 extras =
     # install dependencies - defined in pyproject.toml
     test
-# need to run compile first to ensure MO files are up-to-date
+# need to run compile first to ensure theme files are up-to-date
 deps = 
     sphinx-theme-builder[cli]
     py39-sphinx61: sphinx==6.1.0
@@ -60,8 +60,8 @@ commands =
 
 [testenv:docs-no-checks]
 description = build the documentations without checking for warnings
-base_python = {[testenv:docs]base_python}
-extras = {[testenv:docs]extras}
+base_python = py312
+extras = doc
 commands = sphinx-build audit/site audit/_build {posargs}
 
 # tox run -e compile

From da0b90ddb010ef9bc2e6aaab92c766b25bc65b14 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 19:20:30 +0100
Subject: [PATCH 23/73] Fix if syntax

---
 .github/actions/set-dev-env/action.yml | 2 +-
 .github/workflows/tests_tox.yml        | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 0cf559f1e..2e6851e3a 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -26,4 +26,4 @@ runs:
     # using 12rambau fork until then
     - name: "Install pandoc 📝"
       uses: 12rambau/setup-pandoc@test
-      if: ${{ inputs.pandoc == "True" }}
+      if: ${{ inputs.pandoc }} == "True"
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 05a69159c..fed618b53 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -72,8 +72,10 @@ jobs:
       - name: "Run tests"
         shell: bash
         run: |
+          # check if there is a specific Sphinx version to test
           if [ -n "${{matrix.sphinx-version}}" ]; then
             python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
+          # if not we use the default version
           else
             python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
           fi

From fc588c5c6f770536e1416c51ed01cbfac905604f Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 19:35:44 +0100
Subject: [PATCH 24/73] Clean nox

---
 .github/workflows/tests_tox.yml | 9 +++++----
 tox.ini                         | 5 ++---
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index fed618b53..43386c73b 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -103,8 +103,8 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.12"]
-        sphinx-version: [""]
         include:
+          # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
             sphinx-version: "61"
@@ -118,11 +118,12 @@ jobs:
           python-version: ${{ matrix.python-version }}
           pandoc: "True"
       - name: "Build docs and check for warnings"
-        run: python -Im tox run -e docs
+        run: |
+          # check if there is a specific Sphinx version to test
           if [ -n "${{matrix.sphinx-version}}" ]; then
-          python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
+            python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
           else
-          python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)
+            python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)
           fi
 
   # Run Lighthouse audits on the built site (Ubuntu)
diff --git a/tox.ini b/tox.ini
index 4b31f1ed4..54d811e18 100644
--- a/tox.ini
+++ b/tox.ini
@@ -4,7 +4,7 @@ env_list =
     pre-commit,
     py3{9,10,11,12}-sphinx{61,dev},
     a11y,
-    docs-py3{9,12}-sphinx{61},
+    docs-py3{9,12}{-sphinx61,}
     compile,
     lint
 
@@ -43,8 +43,7 @@ commands =
     playwright install 
     pytest -m "a11y" {posargs}
 
-# tox run -e docs
-[testenv:docs-py3{9,12}-sphinx{61}]
+[testenv:docs-py3{9,12}{-sphinx61,}]
 description = build the documentation and place in docs/_build/html
 base_python = py312
 # suppress Py3.11's new "can't debug frozen modules" warning

From 7cdff015b8125d580610c32ea055296f9fab8eb1 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 19:43:05 +0100
Subject: [PATCH 25/73] Fix base python

---
 .github/workflows/tests_tox.yml | 1 +
 tox.ini                         | 3 +--
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 43386c73b..9a13a02c4 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -118,6 +118,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           pandoc: "True"
       - name: "Build docs and check for warnings"
+        shell: bash
         run: |
           # check if there is a specific Sphinx version to test
           if [ -n "${{matrix.sphinx-version}}" ]; then
diff --git a/tox.ini b/tox.ini
index 54d811e18..3c6cc889d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,6 +5,7 @@ env_list =
     py3{9,10,11,12}-sphinx{61,dev},
     a11y,
     docs-py3{9,12}{-sphinx61,}
+    docs-no-checks,
     compile,
     lint
 
@@ -29,7 +30,6 @@ commands =
     stb compile
     pytest -m "not a11y"
 
-
 # tox run -e a11y
 [testenv:a11y]
 description = run accessibility tests with Playwright and axe-core
@@ -45,7 +45,6 @@ commands =
 
 [testenv:docs-py3{9,12}{-sphinx61,}]
 description = build the documentation and place in docs/_build/html
-base_python = py312
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = 

From 92b1b53d51d1641b29e48bdaa92397d00e8609be Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 20:08:11 +0100
Subject: [PATCH 26/73] Add coverage

---
 .github/workflows/tests_tox.yml | 9 ++++++++-
 tox.ini                         | 9 +++++----
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 9a13a02c4..184306d21 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -79,6 +79,13 @@ jobs:
           else
             python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
           fi
+      - name: "Upload coverage data to GH artifacts "
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data-${{ matrix.python-version }}
+          path: .coverage.*
+          if-no-files-found: ignore
 
   # Only run accessibility tests on the latest Python version (3.12) and Ubuntu
   a11y-tests:
@@ -139,7 +146,7 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Run Lighthouse audits on the built site"
-        run: python -Im tox run -e lighthouse
+        run: python -Im tox run -e docs-no-checks
       - name: "Copy kitchen sink to a tiny site"
         run: |
           mkdir audit/
diff --git a/tox.ini b/tox.ini
index 3c6cc889d..8c0990b26 100644
--- a/tox.ini
+++ b/tox.ini
@@ -2,7 +2,7 @@
 min_version = 4
 env_list =
     pre-commit,
-    py3{9,10,11,12}-sphinx{61,dev},
+    py3{9,10,11,12}{,-sphinx61,-sphinxdev},
     a11y,
     docs-py3{9,12}{-sphinx61,}
     docs-no-checks,
@@ -14,7 +14,7 @@ skip_install = true
 deps = pre-commit
 commands = pre-commit run --all-files
 
-[testenv:py3{9,10,11,12}-sphinx{61,dev}]
+[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}]
 description = run tests across Python versions between 3.9 and 3.12, if a sphinx version is specified it will use that version vs the default in pyproject.toml
 # need to ensure the package is installed in editable mode
 package = editable
@@ -23,12 +23,13 @@ extras =
     test
 # need to run compile first to ensure theme files are up-to-date
 deps = 
+    coverage[toml]
     sphinx-theme-builder[cli]
     py39-sphinx61: sphinx==6.1.0
     py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 commands = 
     stb compile
-    pytest -m "not a11y"
+    coverage run -m pytest -m "not a11y" {posargs}
 
 # tox run -e a11y
 [testenv:a11y]
@@ -43,7 +44,7 @@ commands =
     playwright install 
     pytest -m "a11y" {posargs}
 
-[testenv:docs-py3{9,12}{-sphinx61,}]
+[testenv:docs-py3{9,12}{,-sphinx61}]
 description = build the documentation and place in docs/_build/html
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1

From 29b756dc0a542d945ddae1601446ac746693c5c5 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 2 Apr 2024 20:26:31 +0100
Subject: [PATCH 27/73] Ensure docs are built for a11y tests

---
 pyproject.toml | 5 +++++
 tox.ini        | 5 ++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index f2a15ac81..e64afada2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -122,3 +122,8 @@ branch = true
 
 [tool.coverage.report]
 fail_under = 60
+show_missing = true
+skip_covered = true
+
+[tool.coverage.paths]
+source = ["src"]
diff --git a/tox.ini b/tox.ini
index 8c0990b26..db1c35ffb 100644
--- a/tox.ini
+++ b/tox.ini
@@ -28,7 +28,8 @@ deps =
     py39-sphinx61: sphinx==6.1.0
     py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 commands = 
-    stb compile
+    ; stb compile
+    pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx
     coverage run -m pytest -m "not a11y" {posargs}
 
 # tox run -e a11y
@@ -41,6 +42,8 @@ extras =
     a11y
 allowlist_externals=playwright
 commands = 
+    sbt compile
+    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     playwright install 
     pytest -m "a11y" {posargs}
 

From 0085c77c9ffe8d3fb9392bf45ead5aeac526acfc Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 3 Apr 2024 19:47:53 +0100
Subject: [PATCH 28/73] Update tox commands and envs

---
 .github/workflows/tests_tox.yml | 14 ++++----
 pyproject.toml                  |  2 +-
 tox.ini                         | 63 +++++++++++++++------------------
 3 files changed, 37 insertions(+), 42 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 184306d21..eb9f98d29 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -74,17 +74,17 @@ jobs:
         run: |
           # check if there is a specific Sphinx version to test
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-tests
           # if not we use the default version
           else
-            python -Im tox run -f py$(echo ${{ matrix.python-version }} | tr -d .)
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-tests
           fi
       - name: "Upload coverage data to GH artifacts "
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
         uses: actions/upload-artifact@v4
         with:
           name: coverage-data-${{ matrix.python-version }}
-          path: .coverage.*
+          path: .coverage
           if-no-files-found: ignore
 
   # Only run accessibility tests on the latest Python version (3.12) and Ubuntu
@@ -99,7 +99,7 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Run accessibility tests with playwright 🎭"
-        run: python -Im tox run -e a11y
+        run: python -Im tox run -e py312-docs,a11y-tests
         continue-on-error: true
 
   # Build sites on the 2 major OSes and check for warnings
@@ -129,9 +129,9 @@ jobs:
         run: |
           # check if there is a specific Sphinx version to test
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}
+            python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-docs
           else
-            python -Im tox run -f docs-py$(echo ${{ matrix.python-version }} | tr -d .)
+            python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs
           fi
 
   # Run Lighthouse audits on the built site (Ubuntu)
@@ -155,7 +155,7 @@ jobs:
           printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > audit/site/index.rst
           echo 'html_theme = "pydata_sphinx_theme"' > audit/site/conf.py
           echo '.. toctree::\n   :glob:\n\n   *' >> audit/site/index.rst
-          python -Im tox run -e docs-no-checks
+          python -Im tox run -e docs_no_checks
       - name: "Audit with Lighthouse 🔦"
         uses: treosh/lighthouse-ci-action@v11
         with:
diff --git a/pyproject.toml b/pyproject.toml
index e64afada2..68459b881 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -126,4 +126,4 @@ show_missing = true
 skip_covered = true
 
 [tool.coverage.paths]
-source = ["src"]
+source = ["src", ".tox/py*/**/site-packages"]
diff --git a/tox.ini b/tox.ini
index db1c35ffb..a2c663499 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,53 +1,61 @@
 [tox]
 min_version = 4
 env_list =
-    pre-commit,
-    py3{9,10,11,12}{,-sphinx61,-sphinxdev},
-    a11y,
-    docs-py3{9,12}{-sphinx61,}
-    docs-no-checks,
+    lint,
     compile,
-    lint
+    docs_no_checks,
+    py3{9,12}{,-sphinx61}-docs,
+    py3{9,10,11,12}{,-sphinx61,-sphinxdev}-tests,
+    a11y-tests,
 
-[testenv:pre-commit]
-skip_install = true
-deps = pre-commit
-commands = pre-commit run --all-files
+[testenv]
+deps =
+    lint: pre-commit
+    compile: sphinx-theme-builder[cli]
+extras = 
+    docs_no_checks: doc
+commands = 
+    lint: pre-commit run -a
+    compile: stb compile
+    docs_no_checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build 
 
-[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}]
-description = run tests across Python versions between 3.9 and 3.12, if a sphinx version is specified it will use that version vs the default in pyproject.toml
+; tox run -e py39-tests 
+; tox run -e py39-sphinx61-tests
+[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests]
+description = run tests across Python versions between 3.9 and 3.12, and certain Sphinx versions, if a Sphinx version is specified it will use that version vs the default in pyproject.toml
 # need to ensure the package is installed in editable mode
 package = editable
 extras =
     # install dependencies - defined in pyproject.toml
     test
-# need to run compile first to ensure theme files are up-to-date
 deps = 
     coverage[toml]
-    sphinx-theme-builder[cli]
     py39-sphinx61: sphinx==6.1.0
     py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
+depends = compile
 commands = 
-    ; stb compile
-    pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx
     coverage run -m pytest -m "not a11y" {posargs}
+    coverage report --format=markdown
 
-# tox run -e a11y
-[testenv:a11y]
+# tox run -e py312-docs,a11y-tests
+[testenv:a11y-tests]
 description = run accessibility tests with Playwright and axe-core
 base_python = py312
 extras = 
     # install dependencies - defined in pyproject.toml
     test
     a11y
+depends = 
+    compile, 
+    py312-docs
 allowlist_externals=playwright
 commands = 
-    sbt compile
-    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     playwright install 
     pytest -m "a11y" {posargs}
 
-[testenv:docs-py3{9,12}{,-sphinx61}]
+; tox run -e py39-docs
+; tox run -e py39-sphinx61-docs
+[testenv:py3{9,12}{,-sphinx61}-docs]
 description = build the documentation and place in docs/_build/html
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
@@ -65,16 +73,3 @@ description = build the documentations without checking for warnings
 base_python = py312
 extras = doc
 commands = sphinx-build audit/site audit/_build {posargs}
-
-# tox run -e compile
-[testenv:compile]
-description = "compile the theme's web assets with sphinx-theme-builder"
-deps = sphinx-theme-builder[cli]
-command =
-    stb compile
-
-[testenv:lint]
-description = run linting checks
-base_python = py312
-deps = pre-commit
-commands = pre-commit run -a

From ec5c1e0c089d6f96cf6f0a56ec9afc22b86e3fa7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 3 Apr 2024 19:57:33 +0100
Subject: [PATCH 29/73] Make compile explicit

---
 .github/workflows/tests_tox.yml | 5 +++--
 tox.ini                         | 6 +++---
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index eb9f98d29..6aea3a51a 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -74,10 +74,10 @@ jobs:
         run: |
           # check if there is a specific Sphinx version to test
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-tests
+            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-tests
           # if not we use the default version
           else
-            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-tests
+            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
           fi
       - name: "Upload coverage data to GH artifacts "
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
@@ -155,6 +155,7 @@ jobs:
           printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > audit/site/index.rst
           echo 'html_theme = "pydata_sphinx_theme"' > audit/site/conf.py
           echo '.. toctree::\n   :glob:\n\n   *' >> audit/site/index.rst
+
           python -Im tox run -e docs_no_checks
       - name: "Audit with Lighthouse 🔦"
         uses: treosh/lighthouse-ci-action@v11
diff --git a/tox.ini b/tox.ini
index a2c663499..e092ff548 100644
--- a/tox.ini
+++ b/tox.ini
@@ -19,8 +19,8 @@ commands =
     compile: stb compile
     docs_no_checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build 
 
-; tox run -e py39-tests 
-; tox run -e py39-sphinx61-tests
+; tox run -e compile,py39-tests 
+; tox run -e compile,py39-sphinx61-tests
 [testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests]
 description = run tests across Python versions between 3.9 and 3.12, and certain Sphinx versions, if a Sphinx version is specified it will use that version vs the default in pyproject.toml
 # need to ensure the package is installed in editable mode
@@ -37,7 +37,7 @@ commands =
     coverage run -m pytest -m "not a11y" {posargs}
     coverage report --format=markdown
 
-# tox run -e py312-docs,a11y-tests
+# tox run -e compile,py312-docs,a11y-tests
 [testenv:a11y-tests]
 description = run accessibility tests with Playwright and axe-core
 base_python = py312

From 256d574e64824debb6cae23d84b713682edc4174 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 4 Apr 2024 10:46:50 +0100
Subject: [PATCH 30/73] Skip installs in lint

---
 .github/workflows/tests_tox.yml | 3 +--
 tox.ini                         | 6 +++++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 6aea3a51a..7c04d4460 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -99,6 +99,7 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Run accessibility tests with playwright 🎭"
+        # build PST then run tests
         run: python -Im tox run -e py312-docs,a11y-tests
         continue-on-error: true
 
@@ -145,8 +146,6 @@ jobs:
         uses: ./.github/actions/set-dev-env
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
-      - name: "Run Lighthouse audits on the built site"
-        run: python -Im tox run -e docs-no-checks
       - name: "Copy kitchen sink to a tiny site"
         run: |
           mkdir audit/
diff --git a/tox.ini b/tox.ini
index e092ff548..4edfe413f 100644
--- a/tox.ini
+++ b/tox.ini
@@ -14,6 +14,9 @@ deps =
     compile: sphinx-theme-builder[cli]
 extras = 
     docs_no_checks: doc
+skip_install = 
+    lint: true # do not need to install to lint
+    {compile,docs_no_checks}: false # default but just in case
 commands = 
     lint: pre-commit run -a
     compile: stb compile
@@ -56,7 +59,8 @@ commands =
 ; tox run -e py39-docs
 ; tox run -e py39-sphinx61-docs
 [testenv:py3{9,12}{,-sphinx61}-docs]
-description = build the documentation and place in docs/_build/html
+description = build the documentation and place in docs/_build/html.
+# if run on its own this will package PST install the packaged version and then build the docs
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = 

From 2b5b86260b82989009c6a20a1ab6efca2c1720c0 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 4 Apr 2024 12:56:58 +0100
Subject: [PATCH 31/73] Add coverage upload

---
 .github/workflows/tests_tox.yml | 75 ++++++++++++++++++++++++++-------
 tox.ini                         |  7 +--
 2 files changed, 60 insertions(+), 22 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 7c04d4460..31c512267 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -38,7 +38,7 @@ jobs:
       - name: "Run lint checks 🧹"
         run: python -Im tox run -e lint
 
-  # run our test suite on various combinations of OS / Python version
+  # Run our test suite on various combinations of OS & Python versions
   run-pytest:
     needs: lint
     strategy:
@@ -69,17 +69,19 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           pandoc: "True"
-      - name: "Run tests"
+      - name: "Run tests ✅"
         shell: bash
         run: |
-          # check if there is a specific Sphinx version to test
+          # check if there is a specific Sphinx version to test with
+          # example substitution: tox run -e compile,py39-sphinx61-tests
           if [ -n "${{matrix.sphinx-version}}" ]; then
             python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-tests
           # if not we use the default version
+          # example substitution: tox run -e compile,py39-tests
           else
             python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
           fi
-      - name: "Upload coverage data to GH artifacts "
+      - name: "Upload coverage data to GH artifacts 📤"
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
         uses: actions/upload-artifact@v4
         with:
@@ -89,6 +91,7 @@ jobs:
 
   # Only run accessibility tests on the latest Python version (3.12) and Ubuntu
   a11y-tests:
+    name: "a11y-tests (ubuntu-latest, 3.12)"
     needs: lint
     runs-on: ubuntu-latest
     steps:
@@ -99,18 +102,18 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Run accessibility tests with playwright 🎭"
-        # build PST then run tests
+        # build PST, build docs, then run a11y-tests
         run: python -Im tox run -e py312-docs,a11y-tests
         continue-on-error: true
 
-  # Build sites on the 2 major OSes and check for warnings
+  # Build our docs (PST) on major OSes and check for warnings
   build-site:
     needs: lint
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.12"]
+        python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
         include:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
@@ -125,20 +128,25 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           pandoc: "True"
-      - name: "Build docs and check for warnings"
+      - name: "Build docs and check for warnings 📖"
         shell: bash
         run: |
-          # check if there is a specific Sphinx version to test
+          # check if there is a specific Sphinx version to build with
+          # example substitution: tox run -e docs-py39-sphinx61-docs
           if [ -n "${{matrix.sphinx-version}}" ]; then
             python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-docs
+          # build with the default Sphinx version 
+          # example substitution: tox run -e docs-py312-docs
           else
             python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs
           fi
 
-  # Run Lighthouse audits on the built site (Ubuntu)
+  # Run Lighthouse audits on the built site (kitchen-sink only)
   lighthouse-audit:
     needs: build-site
     runs-on: ubuntu-latest
+    env:
+      DOCS_DIR: "audit"
     steps:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
@@ -148,14 +156,15 @@ jobs:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Copy kitchen sink to a tiny site"
         run: |
-          mkdir audit/
-          mkdir audit/site
-          cp -r docs/examples/kitchen-sink audit/site/kitchen-sink
-          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > audit/site/index.rst
-          echo 'html_theme = "pydata_sphinx_theme"' > audit/site/conf.py
-          echo '.. toctree::\n   :glob:\n\n   *' >> audit/site/index.rst
+          mkdir -p ${{ env.DOCS_DIR }}/site
+          cp -r docs/examples/kitchen-sink ${{ env.DOCS_DIR }}/site/kitchen-sink
+          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > ${{ env.DOCS_DIR }}/site/index.rst
+          echo 'html_theme = "pydata_sphinx_theme"' > ${{ env.DOCS_DIR }}/site/conf.py
+          echo '.. toctree::\n   :glob:\n\n   *' >> ${{ env.DOCS_DIR }}/site/index.rst
 
+          # build docs without checking for warnings
           python -Im tox run -e docs_no_checks
+
       - name: "Audit with Lighthouse 🔦"
         uses: treosh/lighthouse-ci-action@v11
         with:
@@ -163,3 +172,37 @@ jobs:
           temporaryPublicStorage: true
           uploadArtifacts: true
           runs: 3 # Multiple runs to reduce variance
+
+  coverage:
+    name: Combine & check coverage
+    needs: run-pytest
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+      - run: python -Im pip install --upgrade coverage[toml]
+      - name: "Download coverage data 📥"
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-data-*
+          merge-multiple: true
+      - name: "Combine coverage & fail if it's <80%"
+        run: |
+          python -Im coverage combine
+          python -Im coverage html --skip-covered --skip-empty
+
+          # report and write to summary.
+          python -Im coverage report --format=markdown >> $GITHUB_STEP_SUMMARY
+
+          # report again and fail if under 80%.
+          python -Im coverage report --fail-under=80
+      - name: "Upload HTML report if check failed 📤"
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-report
+          path: htmlcov
+        if: ${{ failure() }}
diff --git a/tox.ini b/tox.ini
index 4edfe413f..816276b62 100644
--- a/tox.ini
+++ b/tox.ini
@@ -20,6 +20,7 @@ skip_install =
 commands = 
     lint: pre-commit run -a
     compile: stb compile
+    # can substitute the target directory with posargs
     docs_no_checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build 
 
 ; tox run -e compile,py39-tests 
@@ -71,9 +72,3 @@ deps =
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
-
-[testenv:docs-no-checks]
-description = build the documentations without checking for warnings
-base_python = py312
-extras = doc
-commands = sphinx-build audit/site audit/_build {posargs}

From 8f6c9cb48580e6a0c6dbec5b6671964254df62fb Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 4 Apr 2024 12:59:47 +0100
Subject: [PATCH 32/73] Fix Python version

---
 .github/workflows/tests_tox.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 31c512267..8e64a4754 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -113,7 +113,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+        python-version: ["3.12"]
         include:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest

From 37ea780ab2ce385efca902e3a6e1d7c27639ada4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 4 Apr 2024 13:18:39 +0100
Subject: [PATCH 33/73] Update pre-release workflow

---
 .github/workflows/prerelease.yml | 45 +++++++++++++-------------------
 .github/workflows/tests_tox.yml  |  7 ++---
 tox.ini                          | 35 ++++++++++++++++---------
 3 files changed, 44 insertions(+), 43 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index 967322248..8a98234a2 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -16,38 +16,29 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
         with:
           python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-
-      - name: Install (prerelease) dependencies
+      - name: "Install (prerelease) dependencies"
         run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install --upgrade --pre -e .[doc,test]
-
-      - name: Build docs to store
+          python -Im pip install --upgrade pip wheel setuptools
+      - name: "Build PST docs and check for warnings"
         run: |
-          sphinx-build -b html docs/ docs/_build/html --keep-going -w warnings.txt
-
-      - name: Check that there are no unexpected Sphinx warnings
-        if: matrix.python-version == '3.10'
-        run: python tests/utils/check_warnings.py
-
-      - name: Run the tests
+          # example substitution: tox run -e docs-py312-docs
+          python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs -- --keep-going
+      - name: "Run tests ✅ (no coverage)"
         run: |
-          pytest --color=yes
+          python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov
           echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV
 
       # If either the docs build or the tests resulted in an error, create an issue to note it
-      - name: Create an issue if failure
-        uses: JasonEtco/create-an-issue@v2
-        if: ${{ env.SPHINX_BUILD_UNEXPECTED_WARNINGS || !env.PYTEST_ERRORS }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          filename: .github/prerelease-template.md
+      # - name: Create an issue if failure
+      #   uses: JasonEtco/create-an-issue@v2
+      #   if: ${{ env.SPHINX_BUILD_UNEXPECTED_WARNINGS || !env.PYTEST_ERRORS }}
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #   with:
+      #     filename: .github/prerelease-template.md
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 8e64a4754..4feff647f 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -174,7 +174,7 @@ jobs:
           runs: 3 # Multiple runs to reduce variance
 
   coverage:
-    name: Combine & check coverage
+    name: "Combine & check coverage"
     needs: run-pytest
     runs-on: ubuntu-latest
     steps:
@@ -190,9 +190,10 @@ jobs:
         with:
           pattern: coverage-data-*
           merge-multiple: true
-      - name: "Combine coverage & fail if it's <80%"
+      - name: "Get coverage data & fail if it's <80%"
         run: |
-          python -Im coverage combine
+          # if we decide to check cov across versions and combine
+          # python -Im coverage combine
           python -Im coverage html --skip-covered --skip-empty
 
           # report and write to summary.
diff --git a/tox.ini b/tox.ini
index 816276b62..4abcefbd2 100644
--- a/tox.ini
+++ b/tox.ini
@@ -5,7 +5,7 @@ env_list =
     compile,
     docs_no_checks,
     py3{9,12}{,-sphinx61}-docs,
-    py3{9,10,11,12}{,-sphinx61,-sphinxdev}-tests,
+    py3{9,10,11,12}{,-sphinx61,-sphinxdev}-tests{,-no-cov},
     a11y-tests,
 
 [testenv]
@@ -23,30 +23,38 @@ commands =
     # can substitute the target directory with posargs
     docs_no_checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build 
 
-; tox run -e compile,py39-tests 
-; tox run -e compile,py39-sphinx61-tests
-[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests]
+# tests can be ran with or without coverage (see examples below), it is recommended # to run compile before running tests (see examples below), if you want to skip the 
+# assets compilation step you can run the tests without `compile`
+# tox run -e compile,py39-tests 
+# run tests with a specific Sphinx version
+# tox run -e compile,py39-sphinx61-tests
+# run tests without coverage
+# tox run -e compile,py39-tests-no-cov
+# skip compilation
+# tox run -e py39-tests 
+[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
 description = run tests across Python versions between 3.9 and 3.12, and certain Sphinx versions, if a Sphinx version is specified it will use that version vs the default in pyproject.toml
 # need to ensure the package is installed in editable mode
 package = editable
 extras =
-    # install dependencies - defined in pyproject.toml
-    test
+    test # install dependencies - defined in pyproject.toml
 deps = 
     coverage[toml]
     py39-sphinx61: sphinx==6.1.0
     py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 depends = compile
 commands = 
-    coverage run -m pytest -m "not a11y" {posargs}
-    coverage report --format=markdown
+    py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs}
+    py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage report --format=markdown
+    py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs}
 
+# run accessibility tests with Playwright and axe-core
+# compiling the assets is needed before running the tests
 # tox run -e compile,py312-docs,a11y-tests
 [testenv:a11y-tests]
 description = run accessibility tests with Playwright and axe-core
 base_python = py312
 extras = 
-    # install dependencies - defined in pyproject.toml
     test
     a11y
 depends = 
@@ -57,11 +65,12 @@ commands =
     playwright install 
     pytest -m "a11y" {posargs}
 
-; tox run -e py39-docs
-; tox run -e py39-sphinx61-docs
+# build PST documentation with the default or a specific Sphinx version
+# since we are building the documentation we install the packaged dev version of PST
+# tox run -e py39-docs
+# tox run -e py39-sphinx61-docs
 [testenv:py3{9,12}{,-sphinx61}-docs]
-description = build the documentation and place in docs/_build/html.
-# if run on its own this will package PST install the packaged version and then build the docs
+description = build the documentation and place in docs/_build/html
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 extras = 

From d77fddbc46b814c5cd39dc1fea381fbcfa4a1439 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 4 Apr 2024 16:11:52 +0100
Subject: [PATCH 34/73] Update tox.ini

---
 .github/workflows/prerelease.yml |  3 +++
 .github/workflows/tests_tox.yml  |  2 +-
 tox.ini                          | 28 ++++++++++++++++++----------
 3 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index 8a98234a2..88fc8daca 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -7,6 +7,9 @@ on:
     - cron: "0 5 * * 1,4"
   workflow_dispatch:
 
+env:
+  FORCE_COLOR: "1" # Make tools pretty
+
 jobs:
   prerelease:
     runs-on: ubuntu-latest
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 4feff647f..8dcbe51b3 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -163,7 +163,7 @@ jobs:
           echo '.. toctree::\n   :glob:\n\n   *' >> ${{ env.DOCS_DIR }}/site/index.rst
 
           # build docs without checking for warnings
-          python -Im tox run -e docs_no_checks
+          python -Im tox run -e docs-no-checks
 
       - name: "Audit with Lighthouse 🔦"
         uses: treosh/lighthouse-ci-action@v11
diff --git a/tox.ini b/tox.ini
index 4abcefbd2..0b4eb56b2 100644
--- a/tox.ini
+++ b/tox.ini
@@ -3,25 +3,29 @@ min_version = 4
 env_list =
     lint,
     compile,
-    docs_no_checks,
+    docs-no-checks,
     py3{9,12}{,-sphinx61}-docs,
     py3{9,10,11,12}{,-sphinx61,-sphinxdev}-tests{,-no-cov},
     a11y-tests,
 
+# general tox env configuration
+# these can be run with any py3{9,12} version
+# tox run -e py39-lint  
 [testenv]
 deps =
     lint: pre-commit
     compile: sphinx-theme-builder[cli]
 extras = 
-    docs_no_checks: doc
+    {docs-no-checks, docs-linkcheck}: doc
 skip_install = 
     lint: true # do not need to install to lint
-    {compile,docs_no_checks}: false # default but just in case
+    {compile,docs-no-checks, docs-linkcheck}: false # default but just in case
 commands = 
     lint: pre-commit run -a
     compile: stb compile
-    # can substitute the target directory with posargs
-    docs_no_checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build 
+    # can substitute the target directory
+    docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build
+    docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going
 
 # tests can be ran with or without coverage (see examples below), it is recommended # to run compile before running tests (see examples below), if you want to skip the 
 # assets compilation step you can run the tests without `compile`
@@ -40,7 +44,7 @@ extras =
     test # install dependencies - defined in pyproject.toml
 deps = 
     coverage[toml]
-    py39-sphinx61: sphinx==6.1.0
+    py39-sphinx61-tests: sphinx~=6.1.0
     py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 depends = compile
 commands = 
@@ -73,11 +77,15 @@ commands =
 description = build the documentation and place in docs/_build/html
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
-extras = 
-    # install dependencies - defined in pyproject.toml
-    doc
+extras = {[testenv:docs-no-checks]extras}
 deps = 
-    py39-sphinx61: sphinx==6.1.0
+    py39-sphinx61-docs: sphinx~=6.1.0
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
+
+; [testenv:profile]
+; deps = 
+;     py-spy
+; extras = test
+; commands = 
\ No newline at end of file

From 1bcfa640779b678763ea8ec89c37f3297f12049e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 4 Apr 2024 19:06:39 +0100
Subject: [PATCH 35/73] Small formatting and style fixes to actions

---
 .github/workflows/prerelease.yml | 14 +++++++-------
 .github/workflows/publish.yml    | 17 ++++++++++-------
 .github/workflows/tests_tox.yml  |  2 +-
 tox.ini                          |  1 -
 4 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index 88fc8daca..ca379fdef 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -38,10 +38,10 @@ jobs:
           echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV
 
       # If either the docs build or the tests resulted in an error, create an issue to note it
-      # - name: Create an issue if failure
-      #   uses: JasonEtco/create-an-issue@v2
-      #   if: ${{ env.SPHINX_BUILD_UNEXPECTED_WARNINGS || !env.PYTEST_ERRORS }}
-      #   env:
-      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      #   with:
-      #     filename: .github/prerelease-template.md
+      - name: "Create an issue if failure"
+        uses: JasonEtco/create-an-issue@v2
+        if: ${{ env.SPHINX_BUILD_UNEXPECTED_WARNINGS || !env.PYTEST_ERRORS }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          filename: .github/prerelease-template.md
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 838d90e62..379afc097 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -6,6 +6,9 @@ on:
   release:
     types: ["published"]
 
+env:
+  FORCE_COLOR: "1" # Make tools pretty
+
 jobs:
   tests:
     uses: ./.github/workflows/tests.yml
@@ -14,20 +17,20 @@ jobs:
     needs: [tests] # require tests to pass before deploy runs
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout source
+      - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
-      - name: Set up Python 3.9
+      - name: "Setup Python 🐍"
         uses: actions/setup-python@v5
         with:
           python-version: "3.9"
-      - name: Install gettext for translations
+      - name: "Install gettext for translations 🌐"
         run: |
           sudo apt-get install gettext
-      - name: Build package
+      - name: "Build package 📦"
         run: |
-          python -m pip install -U pip build
-          python -m build
-      - name: Publish
+          python -Im pip install -U pip build
+          python -Im build
+      - name: "Publish to PyPI 🚀"
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 8dcbe51b3..c73e94a0f 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -174,7 +174,7 @@ jobs:
           runs: 3 # Multiple runs to reduce variance
 
   coverage:
-    name: "Combine & check coverage"
+    name: "check coverage"
     needs: run-pytest
     runs-on: ubuntu-latest
     steps:
diff --git a/tox.ini b/tox.ini
index 0b4eb56b2..bac2e541e 100644
--- a/tox.ini
+++ b/tox.ini
@@ -49,7 +49,6 @@ deps =
 depends = compile
 commands = 
     py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs}
-    py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage report --format=markdown
     py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs}
 
 # run accessibility tests with Playwright and axe-core

From 574e294436ef4696b92fc1b66a4857d6ed75c57a Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 5 Apr 2024 15:21:23 +0100
Subject: [PATCH 36/73] Add profiling to CI

---
 .github/workflows/prerelease.yml |  1 +
 .github/workflows/publish.yml    |  3 +-
 .github/workflows/tests_tox.yml  | 23 +++++++-
 tools/profile.py                 | 90 ++++++++++++++++++++++++++++++++
 tox.ini                          | 26 ++++-----
 5 files changed, 128 insertions(+), 15 deletions(-)
 create mode 100644 tools/profile.py

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index ca379fdef..ac44c96aa 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -9,6 +9,7 @@ on:
 
 env:
   FORCE_COLOR: "1" # Make tools pretty
+  PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates
 
 jobs:
   prerelease:
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 379afc097..9844ac855 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -8,13 +8,14 @@ on:
 
 env:
   FORCE_COLOR: "1" # Make tools pretty
+  PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates
 
 jobs:
   tests:
     uses: ./.github/workflows/tests.yml
   publish:
     name: publish
-    needs: [tests] # require tests to pass before deploy runs
+    needs: [tests] # require tests to pass before release
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout repository 🛎"
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index c73e94a0f..dfa16637e 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -11,7 +11,8 @@ concurrency:
 
 env:
   FORCE_COLOR: "1" # Make tools pretty
-  DEFAULT_PYTHON_VERSION: "3.12" # Default Python version to use
+  DEFAULT_PYTHON_VERSION: "3.12" # keep in sync with tox.ini
+  PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates
 
 permissions: {}
 
@@ -207,3 +208,23 @@ jobs:
           name: html-report
           path: htmlcov
         if: ${{ failure() }}
+
+  profile:
+    needs: [build-site, run-pytest]
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout repository 🛎"
+        uses: actions/checkout@v4
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
+        with:
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+      - name: "Run profiling with py-spy 🕵️‍♂️"
+        run: python -Im tox run -e profile-docs
+        continue-on-error: true
+      - name: "Upload profiling data to GH artifacts 📤"
+        uses: actions/upload-artifact@v4
+        with:
+          name: profile-results
+          path: profile.svg
+          if-no-files-found: ignore
diff --git a/tools/profile.py b/tools/profile.py
new file mode 100644
index 000000000..4f955bc46
--- /dev/null
+++ b/tools/profile.py
@@ -0,0 +1,90 @@
+"""Script to profile the build of the test site with py-spy.
+
+This can be called with `python tools/profile.py` and will profile the build of the test site.
+You can additionally configure the number of extra pages to add to the build with the `-n` flag and the output file with the `-o` flag.
+
+$ python tools/profile.py -n 100 -o profile.svg
+
+If running within tox (recommended) this can be run with:
+
+$ tox -e profile-docs -- -n 100 -o profile.svg
+
+"""
+
+import argparse
+import shutil as sh
+import subprocess
+import tempfile
+from pathlib import Path
+from textwrap import dedent
+
+
+def profile_docs(output: str = "profile.svg", n_extra_pages: int = 50) -> None:
+    """Add a bunch of extra pages to the test site and profile the build with py-spy.
+
+    Args:
+        output (str): The output filename for generated chart, defaults to output.svg.
+        n_extra_pages (int): The number of extra pages to add to the build, defaults to 50.
+    """
+    # base path of the test site
+    base_site_path = Path("tests/sites/base")
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+
+        # copy over the base test site to the temporary folder
+        target_path = Path(tmpdir) / base_site_path
+        sh.copytree(base_site_path, target_path)
+        print(f"Copied {base_site_path} to {target_path}")
+
+        # Add a bunch of extra files to increase the build length
+        index_file = target_path / "index.rst"
+        dummy_text = index_file.read_text()
+        dummy_text += dedent(
+            """
+        .. toctree::
+            :glob:
+
+            many/*
+        """
+        )
+        index_file.write_text(dummy_text)
+        many_files_path = target_path / "many"
+        try:
+            many_files_path.mkdir(parents=False)
+        except FileNotFoundError:
+            print(f"Could not create directory {many_files_path}")
+
+        # create a bunch of empty pages to slow the build
+        for page in range(n_extra_pages):
+            (many_files_path / f"{page}.rst").write_text("Test\n====\n\nbody\n")
+
+        # Output directory
+        output_site_path = target_path / "_build"
+
+        # Profile the build
+        print(f"Profiling build with {n_extra_pages} pages with py-spy...")
+
+        subprocess.run(
+            f"py-spy record -o {output} -- sphinx-build {target_path} {output_site_path}/_build".split(),
+            capture_output=True,
+        )
+
+        print(f"py-spy profiler output at this file: {output}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument(
+        "-o", "--output", type=str, help="Output filename, the default is profile.svg"
+    )
+    parser.add_argument(
+        "-n", "--n_pages", type=int, help="Number of extra pages to add to the build"
+    )
+
+    # Parse the arguments
+    args = parser.parse_args()
+    output_file = args.output if args.output else "profile.svg"
+    n_pages = args.n_pages if args.n_pages else 50
+
+    profile_docs(output=output_file, n_extra_pages=n_pages)
diff --git a/tox.ini b/tox.ini
index bac2e541e..c7e64cb08 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,31 +1,36 @@
 [tox]
 min_version = 4
+# list of environments to run by default with tox run
 env_list =
     lint,
     compile,
-    docs-no-checks,
-    py3{9,12}{,-sphinx61}-docs,
-    py3{9,10,11,12}{,-sphinx61,-sphinxdev}-tests{,-no-cov},
+    py312-docs,
+    py3132-tests,
     a11y-tests,
 
 # general tox env configuration
 # these can be run with any py3{9,12} version
 # tox run -e py39-lint  
 [testenv]
+base_python =
+    lint: py312 # keep in sync with tests.yml
 deps =
     lint: pre-commit
     compile: sphinx-theme-builder[cli]
+    profile-docs: py-spy
 extras = 
-    {docs-no-checks, docs-linkcheck}: doc
+    {docs-no-checks, docs-linkcheck, profile-docs}: doc
 skip_install = 
     lint: true # do not need to install to lint
-    {compile,docs-no-checks, docs-linkcheck}: false # default but just in case
+    ; {compile,docs-no-checks, docs-linkcheck}: false # default but just in case
 commands = 
     lint: pre-commit run -a
     compile: stb compile
     # can substitute the target directory
     docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build
     docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going
+    # example tox run -e py39-profile-docs -- -o profile.svg -n 100
+    profile-docs: python ./tools/profile.py {posargs}
 
 # tests can be ran with or without coverage (see examples below), it is recommended # to run compile before running tests (see examples below), if you want to skip the 
 # assets compilation step you can run the tests without `compile`
@@ -56,7 +61,7 @@ commands =
 # tox run -e compile,py312-docs,a11y-tests
 [testenv:a11y-tests]
 description = run accessibility tests with Playwright and axe-core
-base_python = py312
+base_python = py312 # keep in sync with tests.yml
 extras = 
     test
     a11y
@@ -76,15 +81,10 @@ commands =
 description = build the documentation and place in docs/_build/html
 # suppress Py3.11's new "can't debug frozen modules" warning
 set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
+# keep this in sync across all docs environments
 extras = {[testenv:docs-no-checks]extras}
 deps = 
-    py39-sphinx61-docs: sphinx~=6.1.0
+    py39-sphinx61-docs: {py39-sphinx61-tests[deps]}
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
-
-; [testenv:profile]
-; deps = 
-;     py-spy
-; extras = test
-; commands = 
\ No newline at end of file

From 9f84c9289761ea458191af2b4e3e0d3a057c76a5 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 5 Apr 2024 15:51:04 +0100
Subject: [PATCH 37/73] Remove default version

---
 .github/workflows/tests_tox.yml | 1 +
 tox.ini                         | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index dfa16637e..90a8fab4e 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -109,6 +109,7 @@ jobs:
 
   # Build our docs (PST) on major OSes and check for warnings
   build-site:
+    name: "build PST docs"
     needs: lint
     strategy:
       fail-fast: false
diff --git a/tox.ini b/tox.ini
index c7e64cb08..2de274c98 100644
--- a/tox.ini
+++ b/tox.ini
@@ -12,8 +12,6 @@ env_list =
 # these can be run with any py3{9,12} version
 # tox run -e py39-lint  
 [testenv]
-base_python =
-    lint: py312 # keep in sync with tests.yml
 deps =
     lint: pre-commit
     compile: sphinx-theme-builder[cli]

From dfbca62d786c991ab0d805104f708596f9011356 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 5 Apr 2024 16:31:34 +0100
Subject: [PATCH 38/73] Remove trallard debug in ci

---
 .github/workflows/tests_tox.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 90a8fab4e..ab53b535c 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -20,7 +20,6 @@ on:
   push:
     branches:
       - main
-      - trallard/* # allow for personal branches for debugging
   pull_request:
   workflow_call:
   # allow manual triggering of the workflow, while debugging

From 46eb200194bef0182da6efeeae8f492dc05c0139 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 8 Apr 2024 12:13:29 +0100
Subject: [PATCH 39/73] Apply suggestions from code review

Co-authored-by: M Bussonnier <bussonniermatthias@gmail.com>
---
 tools/profile.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/profile.py b/tools/profile.py
index 4f955bc46..694238299 100644
--- a/tools/profile.py
+++ b/tools/profile.py
@@ -65,11 +65,11 @@ def profile_docs(output: str = "profile.svg", n_extra_pages: int = 50) -> None:
         print(f"Profiling build with {n_extra_pages} pages with py-spy...")
 
         subprocess.run(
-            f"py-spy record -o {output} -- sphinx-build {target_path} {output_site_path}/_build".split(),
+            ["py-spy", "record", "-o", output, "--", "sphinx-build", target_path, f" {output_site_path}/_build",
             capture_output=True,
         )
 
-        print(f"py-spy profiler output at this file: {output}")
+        print("py-spy profiler output at this file:", output)
 
 
 if __name__ == "__main__":

From dc202fa7e330f515e45dd4a5d150ff70c723bfd0 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 8 Apr 2024 12:16:31 +0100
Subject: [PATCH 40/73] Add inline comments

---
 .github/actions/set-dev-env/action.yml |  2 +-
 tox.ini                                | 10 +++++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 2e6851e3a..eec4993d1 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -3,7 +3,7 @@ description: Create a PST dev environment
 
 inputs:
   python-version:
-    description: Python version to use
+    description: Default Python version to use if none is specified
     required: false
     default: "3.12"
   pandoc:
diff --git a/tox.ini b/tox.ini
index 2de274c98..b3662915b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,11 +1,13 @@
 [tox]
 min_version = 4
 # list of environments to run by default with tox run
+# using Python 3.12 as the default, this needs to be kept in line with
+# .github/actions/set-dev-env/action.yml
 env_list =
     lint,
     compile,
     py312-docs,
-    py3132-tests,
+    py312-tests,
     a11y-tests,
 
 # general tox env configuration
@@ -30,7 +32,8 @@ commands =
     # example tox run -e py39-profile-docs -- -o profile.svg -n 100
     profile-docs: python ./tools/profile.py {posargs}
 
-# tests can be ran with or without coverage (see examples below), it is recommended # to run compile before running tests (see examples below), if you want to skip the 
+# tests can be ran with or without coverage (see examples below), it is recommended # to run compile before running 
+# tests (see examples below), if you want to skip the 
 # assets compilation step you can run the tests without `compile`
 # tox run -e compile,py39-tests 
 # run tests with a specific Sphinx version
@@ -40,7 +43,8 @@ commands =
 # skip compilation
 # tox run -e py39-tests 
 [testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
-description = run tests across Python versions between 3.9 and 3.12, and certain Sphinx versions, if a Sphinx version is specified it will use that version vs the default in pyproject.toml
+description = "run tests across Python versions between 3.9 and 3.12, and certain Sphinx versions. If a Sphinx version
+is specified it will use that version vs the default in pyproject.toml"
 # need to ensure the package is installed in editable mode
 package = editable
 extras =

From 185efc6cbc80ac155a5d1f925398ef910246e3c6 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 8 Apr 2024 12:22:14 +0100
Subject: [PATCH 41/73] Add Python 3.13 so we can start testing against it

---
 .github/workflows/prerelease.yml | 2 +-
 .github/workflows/tests_tox.yml  | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index ac44c96aa..9a92828a2 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -29,7 +29,7 @@ jobs:
       - name: "Install (prerelease) dependencies"
         run: |
           python -Im pip install --upgrade pip wheel setuptools
-      - name: "Build PST docs and check for warnings"
+      - name: "Build PST docs and check for warnings 📖"
         run: |
           # example substitution: tox run -e docs-py312-docs
           python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs -- --keep-going
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index ab53b535c..b448df3b9 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -45,7 +45,7 @@ jobs:
       fail-fast: true
       matrix:
         os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13-dev"]
         sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version
@@ -55,6 +55,7 @@ jobs:
             # newest Python version with the newest Sphinx version
           - os: ubuntu-latest
             python-version: "3.12"
+            # Sphinx HEAD
             sphinx-version: "dev"
         exclude:
           # Python 3.9 is not supported on macOS 14 - https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json

From 4d35885d85440cc5950e5eb85eee0472a1b92a7e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 8 Apr 2024 12:47:46 +0100
Subject: [PATCH 42/73] :pencil2: Fix typo - profile

---
 tools/profile.py | 11 ++++++++++-
 tox.ini          |  3 +--
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/tools/profile.py b/tools/profile.py
index 694238299..3a46572b1 100644
--- a/tools/profile.py
+++ b/tools/profile.py
@@ -65,7 +65,16 @@ def profile_docs(output: str = "profile.svg", n_extra_pages: int = 50) -> None:
         print(f"Profiling build with {n_extra_pages} pages with py-spy...")
 
         subprocess.run(
-            ["py-spy", "record", "-o", output, "--", "sphinx-build", target_path, f" {output_site_path}/_build",
+            [
+                "py-spy",
+                "record",
+                "-o",
+                output,
+                "--",
+                "sphinx-build",
+                target_path,
+                f" {output_site_path}/_build",
+            ],
             capture_output=True,
         )
 
diff --git a/tox.ini b/tox.ini
index b3662915b..1f15e9c22 100644
--- a/tox.ini
+++ b/tox.ini
@@ -43,8 +43,7 @@ commands =
 # skip compilation
 # tox run -e py39-tests 
 [testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
-description = "run tests across Python versions between 3.9 and 3.12, and certain Sphinx versions. If a Sphinx version
-is specified it will use that version vs the default in pyproject.toml"
+description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml"
 # need to ensure the package is installed in editable mode
 package = editable
 extras =

From dc3bc4f4d0af6ec0cc3ecda2c00ccf3af5861d93 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 8 Apr 2024 19:12:17 +0100
Subject: [PATCH 43/73] Add Python 3.13 so we can start testing against it

---
 .github/actions/set-dev-env/action.yml | 1 +
 .github/workflows/tests_tox.yml        | 2 +-
 tox.ini                                | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index eec4993d1..9a4d1b356 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -20,6 +20,7 @@ runs:
         python-version: ${{ inputs.python-version }}
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
+        allow-prereleases: true
     - run: python -Im pip install tox-uv
       shell: bash
     # waiting for https://github.com/nikeee/setup-pandoc/pull/8
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index b448df3b9..ad75cea81 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -45,7 +45,7 @@ jobs:
       fail-fast: true
       matrix:
         os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13-dev"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
         sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version
diff --git a/tox.ini b/tox.ini
index 1f15e9c22..31088e5ae 100644
--- a/tox.ini
+++ b/tox.ini
@@ -42,7 +42,7 @@ commands =
 # tox run -e compile,py39-tests-no-cov
 # skip compilation
 # tox run -e py39-tests 
-[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
+[testenv:py3{9,10,11,12,13}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
 description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml"
 # need to ensure the package is installed in editable mode
 package = editable

From 90b273950a9184d7a4dab98aa3dace24f6fd831e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 9 Apr 2024 13:55:36 +0100
Subject: [PATCH 44/73] Ensure we can run profiling in CI

---
 .github/workflows/tests_tox.yml |  5 +++--
 tools/github_actions_install.sh | 18 ------------------
 tools/profile.py                |  2 +-
 tox.ini                         |  2 +-
 4 files changed, 5 insertions(+), 22 deletions(-)
 delete mode 100755 tools/github_actions_install.sh

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index ad75cea81..3e06dc09a 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -221,11 +221,12 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: "Run profiling with py-spy 🕵️‍♂️"
-        run: python -Im tox run -e profile-docs
+        # profiling needs to be run as sudo
+        run: sudo python -Im tox run -e py312-profile-docs -- -o docbuild_profile.svg
         continue-on-error: true
       - name: "Upload profiling data to GH artifacts 📤"
         uses: actions/upload-artifact@v4
         with:
           name: profile-results
-          path: profile.svg
+          path: docbuild_profile.svg
           if-no-files-found: ignore
diff --git a/tools/github_actions_install.sh b/tools/github_actions_install.sh
deleted file mode 100755
index fba8346ea..000000000
--- a/tools/github_actions_install.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/bin/bash
-
-# First arg ($1) is the extras_require to install, optional second arg
-# ($2) is an extra dependency (currently just nox on one run)
-set -eo pipefail
-export PYTHONUTF8=1
-if [[ "$SPHINX_VERSION" == "" ]]; then
-    SPHINX_INSTALL=""
-elif [[ "$SPHINX_VERSION" == "dev" ]]; then
-    SPHINX_INSTALL="sphinx[test]@https://codeload.github.com/sphinx-doc/sphinx/zip/refs/heads/master"
-elif [[ "$SPHINX_VERSION" == "old" ]]; then
-    SPHINX_INSTALL="sphinx[test]==6.1.0"
-else  # not used currently but easy enough
-    SPHINX_INSTALL="sphinx[test]==$SPHINX_VERSION"
-fi
-set -x  # print commands
-python -m pip install --upgrade pip wheel setuptools
-python -m pip install -e .["$1"] ${SPHINX_INSTALL} $2
diff --git a/tools/profile.py b/tools/profile.py
index 3a46572b1..8d5b3a50b 100644
--- a/tools/profile.py
+++ b/tools/profile.py
@@ -78,7 +78,7 @@ def profile_docs(output: str = "profile.svg", n_extra_pages: int = 50) -> None:
             capture_output=True,
         )
 
-        print("py-spy profiler output at this file:", output)
+    print("py-spy profiler output at this file:", output)
 
 
 if __name__ == "__main__":
diff --git a/tox.ini b/tox.ini
index 31088e5ae..9e1e78558 100644
--- a/tox.ini
+++ b/tox.ini
@@ -22,7 +22,7 @@ extras =
     {docs-no-checks, docs-linkcheck, profile-docs}: doc
 skip_install = 
     lint: true # do not need to install to lint
-    ; {compile,docs-no-checks, docs-linkcheck}: false # default but just in case
+    profile-docs: true # avoids issues with py-spy and setting the git repo
 commands = 
     lint: pre-commit run -a
     compile: stb compile

From 5887ea2830a4ce98bac3ecfca4459674528167b9 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 9 Apr 2024 15:39:49 +0100
Subject: [PATCH 45/73] Remove 13 for now

---
 .github/workflows/tests_tox.yml | 2 +-
 tox.ini                         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 3e06dc09a..9aca98a98 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -45,7 +45,7 @@ jobs:
       fail-fast: true
       matrix:
         os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
         sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version
diff --git a/tox.ini b/tox.ini
index 9e1e78558..fe6a16b22 100644
--- a/tox.ini
+++ b/tox.ini
@@ -42,7 +42,7 @@ commands =
 # tox run -e compile,py39-tests-no-cov
 # skip compilation
 # tox run -e py39-tests 
-[testenv:py3{9,10,11,12,13}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
+[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
 description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml"
 # need to ensure the package is installed in editable mode
 package = editable

From 5f435b1547af81011bc4ebafe642e60f1b6a8b5c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 10 Apr 2024 13:08:53 +0100
Subject: [PATCH 46/73] Add script for now - install gh

---
 tools/github_actions_install.sh | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 tools/github_actions_install.sh

diff --git a/tools/github_actions_install.sh b/tools/github_actions_install.sh
new file mode 100644
index 000000000..fba8346ea
--- /dev/null
+++ b/tools/github_actions_install.sh
@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# First arg ($1) is the extras_require to install, optional second arg
+# ($2) is an extra dependency (currently just nox on one run)
+set -eo pipefail
+export PYTHONUTF8=1
+if [[ "$SPHINX_VERSION" == "" ]]; then
+    SPHINX_INSTALL=""
+elif [[ "$SPHINX_VERSION" == "dev" ]]; then
+    SPHINX_INSTALL="sphinx[test]@https://codeload.github.com/sphinx-doc/sphinx/zip/refs/heads/master"
+elif [[ "$SPHINX_VERSION" == "old" ]]; then
+    SPHINX_INSTALL="sphinx[test]==6.1.0"
+else  # not used currently but easy enough
+    SPHINX_INSTALL="sphinx[test]==$SPHINX_VERSION"
+fi
+set -x  # print commands
+python -m pip install --upgrade pip wheel setuptools
+python -m pip install -e .["$1"] ${SPHINX_INSTALL} $2

From 876cc4355b7b49c7e2cdb5522adc5245165eebb4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 16 Apr 2024 11:51:34 +0200
Subject: [PATCH 47/73] Use relative path for executable

---
 .github/workflows/tests.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index b32f6964c..caddf9e72 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -83,7 +83,7 @@ jobs:
         shell: bash
         # setting shell to BASH and using PYTHONUTF8 env var makes the editable
         # install work on Windows even though there are emoji in our README
-        run: tools/github_actions_install.sh test
+        run: ./tools/github_actions_install.sh test
       - name: Show installed versions
         run: python -m pip list
       - name: Compile MO files

From 0b7413029445e059a5310543178cd715cf2c158a Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Tue, 16 Apr 2024 13:40:18 +0200
Subject: [PATCH 48/73] make install scritp executable

---
 tools/github_actions_install.sh | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 tools/github_actions_install.sh

diff --git a/tools/github_actions_install.sh b/tools/github_actions_install.sh
old mode 100644
new mode 100755

From 039c53038c6ee508e19d7ed374723ce3b0bfff0f Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Thu, 25 Apr 2024 15:38:47 +0200
Subject: [PATCH 49/73] try to fix sphinx test

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 8fec1f767..d729d1708 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -77,7 +77,7 @@ doc = [
   "ipyleaflet",
   "colorama",
 ]
-test = ["pytest", "pytest-cov", "pytest-regressions"]
+test = ["pytest", "pytest-cov", "pytest-regressions", 'sphinx[test]']
 dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox"]
 a11y = ["pytest-playwright"]
 

From 904ffeba5fc4c2c428827ad7b2eb3e805a5d0c86 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 8 May 2024 17:16:53 +0100
Subject: [PATCH 50/73] Fix Python version for profiling

---
 .github/workflows/tests_tox.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 9aca98a98..3a84f4468 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -219,10 +219,11 @@ jobs:
       - name: "Setup CI environment 🛠"
         uses: ./.github/actions/set-dev-env
         with:
-          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
+          # 3.12 is not supported by py-spy yet
+          python-version: "3.11"
       - name: "Run profiling with py-spy 🕵️‍♂️"
         # profiling needs to be run as sudo
-        run: sudo python -Im tox run -e py312-profile-docs -- -o docbuild_profile.svg
+        run: sudo python -Im tox run -e py311-profile-docs -- -o docbuild_profile.svg
         continue-on-error: true
       - name: "Upload profiling data to GH artifacts 📤"
         uses: actions/upload-artifact@v4

From 491c59a20bdfd03a29982c779b0e0500a3ebec73 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 8 May 2024 17:29:57 +0100
Subject: [PATCH 51/73] Update release workflow

---
 .github/workflows/prerelease.yml | 1 +
 .github/workflows/publish.yml    | 5 +++--
 .github/workflows/tests_tox.yml  | 1 +
 tox.ini                          | 6 +++---
 4 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index 9a92828a2..e7cfd9d50 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -35,6 +35,7 @@ jobs:
           python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs -- --keep-going
       - name: "Run tests ✅ (no coverage)"
         run: |
+          # this will compile the assets then run the tests
           python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov
           echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV
 
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index ff973840e..93a2a7c33 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -27,10 +27,11 @@ jobs:
       - name: "Checkout repository 🛎"
         uses: actions/checkout@v4
 
-      - name: "Set up Python 3.9"
-        uses: actions/setup-python@v5
+      - name: "Setup CI environment 🛠"
+        uses: ./.github/actions/set-dev-env
         with:
           python-version: "3.9"
+          pandoc: "False"
 
       - name: "Install gettext for translations 🌐"
         run: |
diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/tests_tox.yml
index 3a84f4468..91305d1b5 100644
--- a/.github/workflows/tests_tox.yml
+++ b/.github/workflows/tests_tox.yml
@@ -73,6 +73,7 @@ jobs:
       - name: "Run tests ✅"
         shell: bash
         run: |
+          # this will compile the assets then run the tests
           # check if there is a specific Sphinx version to test with
           # example substitution: tox run -e compile,py39-sphinx61-tests
           if [ -n "${{matrix.sphinx-version}}" ]; then
diff --git a/tox.ini b/tox.ini
index fe6a16b22..f7b656692 100644
--- a/tox.ini
+++ b/tox.ini
@@ -32,10 +32,10 @@ commands =
     # example tox run -e py39-profile-docs -- -o profile.svg -n 100
     profile-docs: python ./tools/profile.py {posargs}
 
-# tests can be ran with or without coverage (see examples below), it is recommended # to run compile before running 
-# tests (see examples below), if you want to skip the 
-# assets compilation step you can run the tests without `compile`
+# tests can be ran with or without coverage (see examples below), it is recommended to run compile before running tests (see examples below), 
 # tox run -e compile,py39-tests 
+# if you want to skip the assets compilation step you can run the tests without `compile`
+# tox run -e py39-tests 
 # run tests with a specific Sphinx version
 # tox run -e compile,py39-sphinx61-tests
 # run tests without coverage

From 7a6d85ce76faeb0d961d378d91ea8cffc4008d71 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 14:16:04 +0100
Subject: [PATCH 52/73] :memo: Update dev setup docs

---
 docs/community/setup.md | 73 ++++++++++++++++++++++++++---------------
 1 file changed, 46 insertions(+), 27 deletions(-)

diff --git a/docs/community/setup.md b/docs/community/setup.md
index 309e53ece..49ff1dffa 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -2,7 +2,8 @@
 
 This section covers the simplest way to get started developing this theme locally so that you can contribute.
 It uses automation and as few steps as possible to get things done.
-If you'd like to do more operations manually, see [](topics/manual-dev.md).
+
+If you are comfortable with and prefer a more manual setup refer to the [](topics/manual-dev.md) section.
 
 ## Workflow for contributing changes
 
@@ -16,9 +17,10 @@ of:
 - work through code review
 
 For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR.
-To access this, click on the {{ rtd }} preview in the CI/CD jobs.
+To access this preview, click on the {{ rtd }} preview in the CI/CD jobs (GitHub checks section
+at the bottom of a PR, note you might need to click on "Show all checks" to access the job).
 
-The sections below cover the steps to take in more detail.
+The sections below cover the contribution steps in more detail.
 
 ## Clone the repository
 
@@ -41,27 +43,27 @@ To simplify this process, we use a few helper tools:
 
 - [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) compiles web assets in an automated way.
 - [pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits.
-- [nox](https://nox.thea.codes/) for automating common development tasks.
+- [tox](https://tox.wiki/en/latest/index.html) for automating common development tasks.
 - [pandoc](https://pandoc.org/) the universal document converter.
 
-In particular, `nox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
+In particular, `tox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
 The rest of this guide focuses on using `nox` to start with a basic environment.
 
 ```{seealso}
 The information on this page covers the basics to get you started, for information about manually compiling assets, see [](topics/manual-dev.md).
 ```
 
-### Setup `nox`
+### Setup `tox`
 
-To start, install `nox`:
+To start, install `tox`:
 
 ```console
-$ pip install nox
+$ pip install tox
 ```
 
-You can call `nox` from the command line to perform common actions that are needed in building the theme.
-`nox` operates with isolated environments, so each action has its own packages installed in a local directory (`.nox`).
-For common development actions, you'll only need to use `nox` and won't need to set up any other packages.
+You can call `tox` from the command line to perform common actions that are needed in building the theme.
+`tox` operates with isolated environments, so each action has its own packages installed in a local directory (`.tox`).
+For common development actions, you'll only need to use `tox` and won't need to set up any other packages.
 
 ### Setup `pre-commit`
 
@@ -82,24 +84,32 @@ $ pre-commit install
 
 This will install the necessary dependencies to run `pre-commit` every time you make a commit with Git.
 
-:::{note}
-Your `pre-commit` dependencies will be installed in the environment from which you're calling `pre-commit`, `nox`, etc.
-They will not be installed in the isolated environments used by `nox`.
-:::
+```{note}
+Your `pre-commit` dependencies will be installed in the environment from which you're calling `pre-commit`, `tox`, etc.
+They will not be installed in the isolated environments used by `tox`.
+```
+
+Alternatively, if you do not want to install pre-commit and its dependencies globally, you can use `tox` to run the checks:
+
+```python
+tox -e run lint
+```
+
+The caveat to using `tox` is that this will not install the required hooks to run the checks automatically before each commit, so you need to run this manually.
 
 ## Build the documentation
 
-Now that you have `nox` installed and cloned the repository, you should be able to build the documentation locally.
+Now that you have `tox` installed and cloned the repository, you should be able to build the documentation locally.
 
 To build the documentation with `nox`, run the following command:
 
 ```console
-$ nox -s docs
+$ tox run -e docs-dev
 ```
 
 This will install the necessary dependencies and build the documentation located in the `docs/` folder.
-They will be placed in a `docs/_build/html` folder.
-If the docs have already been built, it will only build new pages that have been updated.
+The generated documentation will be placed in a `docs/_build/html` folder.
+If the docs have already been built, it will only re-build the pages that have been updated.
 You can open one of the HTML files there to preview the documentation locally.
 
 Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with:
@@ -115,28 +125,30 @@ This will print a local URL that you can open in a browser to explore the HTML f
 Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds.
 
 1. **Make an edit to a page**. For example, add a word or fix a typo on any page.
-2. **Rebuild the documentation** with `nox -s docs`
+2. **Rebuild the documentation** with `tox run -e docs-dev`
 
-It should go much faster this time because `nox` is re-using the previously created environment, and because Sphinx has cached the pages that you didn't change.
+It should go much faster this time because `tox` is re-using the previously created environment, and because Sphinx has cached the pages that you didn't change.
 
 ## Compile the CSS/JS assets
 
 The source files for CSS and JS assets are in `src/pydata_sphinx_theme/assets`.
 These are then built and bundled with the theme (e.g., `scss` is turned into `css`).
 
-To compile the CSS/JS assets with `nox`, run the following command:
+To compile the CSS/JS assets with `tox`, run the following command:
 
 ```console
-$ nox -s compile
+$ tox -e run compile
 ```
 
 This will compile all assets and place them in the appropriate folder to be used with documentation builds.
 
 ```{note}
 Compiled assets are **not committed to git**.
-The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to git history.
+The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to Git history.
 ```
 
+<!-- TODO update or remove -->
+
 ## Run a development server
 
 You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window.
@@ -162,7 +174,7 @@ will cause the development server to do the following:
 
 ## Run the tests
 
-This theme uses `pytest` for its testing. There is a lightweight fixture defined
+This theme uses `pytest` and `playwright` for testing. There is a lightweight fixture defined
 in the `test_build.py` script that makes it straightforward to run a Sphinx build using
 this theme and inspect the results. There are also several automated accessibility checks in
 `test_a11y.py`.
@@ -184,11 +196,18 @@ pass.
 To run the build tests with `nox`, run the following command:
 
 ```console
-$ nox -s test
+# this will compile the assets and run the tests (with test coverage)
+$ tox -e run compile,tests
+
+# to run the tests without pre-compiling the assets and without coverage (for example if you recently compiled the assets)
+$ tox -e run tests-no-cov
 ```
 
 To run the accessibility checks:
 
 ```console
-$ nox -s a11y
+$ tox -e run compile,docs, a11y-tests
+
+# to run the tests without pre-compiling the assets and without re-building the docs (for example if you recently compiled the assets or built the docs)
+$ tox -e run a11y-tests
 ```

From f44df2a33d088d6dc99623c49f74529d4c6d6e05 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 14:16:32 +0100
Subject: [PATCH 53/73] :heavy_plus_sign: Add pandoc to prerelease workflow

---
 .github/prerelease-template.md   |  3 ++-
 .github/workflows/prerelease.yml |  3 ++-
 tox.ini                          | 14 ++++++++++++++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/.github/prerelease-template.md b/.github/prerelease-template.md
index ff8e27c10..a127a1e6e 100644
--- a/.github/prerelease-template.md
+++ b/.github/prerelease-template.md
@@ -4,6 +4,7 @@ assignees: choldgraf
 labels: bug, enhancement
 ---
 
-A prerelease of one of our dependencies failed. See the
+A prerelease of one of our dependencies failed.
+See the
 [action log](https://github.com/{{ env.GITHUB_ACTION_REPOSITORY }}/actions/runs/{{ env.GITHUB_RUN_ID }})
 for more details.
diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml
index e7cfd9d50..eee2fa340 100644
--- a/.github/workflows/prerelease.yml
+++ b/.github/workflows/prerelease.yml
@@ -26,7 +26,8 @@ jobs:
         uses: ./.github/actions/set-dev-env
         with:
           python-version: ${{ matrix.python-version }}
-      - name: "Install (prerelease) dependencies"
+          pandoc: "True"
+      - name: "Install (prerelease) dependencies 📦"
         run: |
           python -Im pip install --upgrade pip wheel setuptools
       - name: "Build PST docs and check for warnings 📖"
diff --git a/tox.ini b/tox.ini
index f7b656692..287d4cfda 100644
--- a/tox.ini
+++ b/tox.ini
@@ -89,3 +89,17 @@ deps =
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
+
+# recommended for local development, this command will build the PST documentation
+# with the default Sphinx version and the PST installed in editable mode
+# tox run -e docs-dev
+[testenv:docs-dev]
+description = build the documentation and place in docs/_build/html (dev mode)
+# suppress Py3.11's new "can't debug frozen modules" warning
+set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
+# keep this in sync across all docs environments
+extras = {[testenv:docs-no-checks]extras}
+package = editable
+commands =
+    sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
+    python tests/utils/check_warnings.py

From 6b2dcca8255a54911ccc62059c5a89787c807fc5 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 16:00:05 +0100
Subject: [PATCH 54/73] Update manual dev instructions

---
 docs/community/topics/manual-dev.md | 16 +++++-----------
 1 file changed, 5 insertions(+), 11 deletions(-)

diff --git a/docs/community/topics/manual-dev.md b/docs/community/topics/manual-dev.md
index 2b05d5888..e2a7ca098 100644
--- a/docs/community/topics/manual-dev.md
+++ b/docs/community/topics/manual-dev.md
@@ -2,7 +2,7 @@
 
 # Set up a manual development environment
 
-If you prefer not to use automation tools like `nox`, or want to have more control over the specific version of packages that you'd like installed, you may also manually set up a development environment locally.
+If you prefer not to use automation tools like `tox`, or want to have more control over the specific version of packages that you'd like installed, you may set your local development environment manually.
 
 To do so, follow the instructions on this page.
 
@@ -12,18 +12,12 @@ This is optional, but it's best to start with a fresh development environment so
 
 To do so, use a tool like [conda](https://docs.conda.io/en/latest/), [mamba](https://github.com/mamba-org/mamba), or [virtualenv](https://virtualenv.pypa.io/).
 
-## Install dependencies
+## Pre-requisites
 
-You must install `sphinx-theme-builder` and Pandoc.
+Before you start, ensure that you have the following installed:
 
-We use the `sphinx-theme-builder` to install `nodejs` locally and to compile all CSS and JS assets needed for the theme.
-Install it like so (note the `cli` option so that we can run it from the command line):
-
-```console
-$ pip install "sphinx-theme-builder[cli]"
-```
-
-We use `nbsphinx` to support notebook (.ipynb) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) at a system level (or within a Conda environment).
+- Python >= 3.9
+- [Pandoc](https://pandoc.org/installing.html): we use `nbsphinx` to support notebook (.ipynb) files in the documentation, which requires [installing Pandoc](https://pandoc.org/installing.html) at a system level (or within a Conda environment).
 
 ## Clone the repository locally
 

From 0532405eaf3c071795f0311d048cb9188a43e883 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 17:37:15 +0100
Subject: [PATCH 55/73] Add notes about codespaces

---
 .devcontainer/devcontainer.json | 2 ++
 docs/community/setup.md         | 9 ++++++++-
 pyproject.toml                  | 2 +-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 5f99475b8..fbe437c34 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -3,7 +3,9 @@
   "name": "Python 3",
   "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
   "features": {
+    // TODO: remove nox before merge
     "ghcr.io/devcontainers-contrib/features/nox:2": {},
+    "ghcr.io/devcontainers-contrib/features/tox:2": {},
     "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
     "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {},
     "ghcr.io/devcontainers/features/node:1": {}
diff --git a/docs/community/setup.md b/docs/community/setup.md
index 49ff1dffa..33d593b80 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -16,7 +16,7 @@ of:
 - fix findings of various linters and checks
 - work through code review
 
-For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR.
+For each pull request (PR), the documentation is built and deployed to make it easier to review the changes in the PR.
 To access this preview, click on the {{ rtd }} preview in the CI/CD jobs (GitHub checks section
 at the bottom of a PR, note you might need to click on "Show all checks" to access the job).
 
@@ -211,3 +211,10 @@ $ tox -e run compile,docs, a11y-tests
 # to run the tests without pre-compiling the assets and without re-building the docs (for example if you recently compiled the assets or built the docs)
 $ tox -e run a11y-tests
 ```
+
+## GitHub codespaces
+
+If you have good internet connectivity and want a temporary set-up, it is often faster to work on PyData Sphinx Theme
+in a Codespaces environment. Once your Codespaces instance is set up, you can run the `tox` commands above to build
+the documentation, compile the assets, and run the tests.
+For documentation on how to get started with Codespaces, see [the Codespaces documentation](https://docs.github.com/en/codespaces).
diff --git a/pyproject.toml b/pyproject.toml
index 1a8055de2..0b155ef69 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -78,7 +78,7 @@ doc = [
   "colorama",
 ]
 test = ["pytest", "pytest-cov", "pytest-regressions", 'sphinx[test]']
-dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox"]
+dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
 a11y = ["pytest-playwright"]
 
 [project.entry-points]

From 800b89cc0347148a9c7f7c023fa770260b77144c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 18:28:39 +0100
Subject: [PATCH 56/73] Add live-docs to tox

---
 docs/community/setup.md |  9 ++++-----
 pyproject.toml          |  1 +
 tox.ini                 | 15 +++++++++++++++
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/docs/community/setup.md b/docs/community/setup.md
index 33d593b80..7e1af82ce 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -101,7 +101,7 @@ The caveat to using `tox` is that this will not install the required hooks to ru
 
 Now that you have `tox` installed and cloned the repository, you should be able to build the documentation locally.
 
-To build the documentation with `nox`, run the following command:
+To build the documentation with `tox`, run the following command:
 
 ```console
 $ tox run -e docs-dev
@@ -147,16 +147,14 @@ Compiled assets are **not committed to git**.
 The `sphinx-theme-builder` will bundle these assets automatically when we make a new release, but we do not manually commit these compiled assets to Git history.
 ```
 
-<!-- TODO update or remove -->
-
 ## Run a development server
 
 You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window.
 
-To run the development server with `nox`, run the following command:
+To run the development server with `tox`, run the following command:
 
 ```console
-$ nox -s docs-live
+$ tox -e run docs-live
 ```
 
 When working on the theme, making changes to any of these directories:
@@ -164,6 +162,7 @@ When working on the theme, making changes to any of these directories:
 - `src/js/index.js`
 - `src/scss/index.scss`
 - `docs/**/*.rst`
+- `docs/**/*.md`
 - `docs/**/*.py`
 
 will cause the development server to do the following:
diff --git a/pyproject.toml b/pyproject.toml
index 0b155ef69..6e28eb6df 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -80,6 +80,7 @@ doc = [
 test = ["pytest", "pytest-cov", "pytest-regressions", 'sphinx[test]']
 dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
 a11y = ["pytest-playwright"]
+i18n = ["Babel", "jinja2"]
 
 [project.entry-points]
 "sphinx.html_themes" = { pydata_sphinx_theme = "pydata_sphinx_theme" }
diff --git a/tox.ini b/tox.ini
index 287d4cfda..2c4855af3 100644
--- a/tox.ini
+++ b/tox.ini
@@ -103,3 +103,18 @@ package = editable
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py
+
+
+[testenv:docs-live]
+description = "Build and serve the documentation with live-reload"
+extras = 
+    dev
+    i18n
+package = editable
+deps = 
+    sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b
+# suppress Py3.11's new "can't debug frozen modules" warning
+set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
+commands = 
+    pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx
+    stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db
\ No newline at end of file

From 7ebd352b9978ccc00dbceb23bee1c4eab87db917 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 18:32:00 +0100
Subject: [PATCH 57/73] Remove obsolete nox refs

---
 .devcontainer/devcontainer.json |   2 -
 .github/workflows/tests.yml     | 273 --------------------------------
 docs/community/setup.md         |   4 +-
 docs/community/topics/assets.md |   2 +-
 pyproject.toml                  |   2 +-
 tests/README.md                 |   2 +-
 6 files changed, 5 insertions(+), 280 deletions(-)
 delete mode 100644 .github/workflows/tests.yml

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index fbe437c34..3a485357e 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -3,8 +3,6 @@
   "name": "Python 3",
   "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
   "features": {
-    // TODO: remove nox before merge
-    "ghcr.io/devcontainers-contrib/features/nox:2": {},
     "ghcr.io/devcontainers-contrib/features/tox:2": {},
     "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
     "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {},
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
deleted file mode 100644
index b39e959d5..000000000
--- a/.github/workflows/tests.yml
+++ /dev/null
@@ -1,273 +0,0 @@
-name: continuous-integration
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
-  cancel-in-progress: true
-
-# README
-# ======
-#
-# All the jobs are defined with `matrix` for OS and Python version, even if we
-# only run them on one combination of OS/Python. The reason for this is you get
-# a nice side-effect that the OS and Python version of the job are listed in
-# parentheses next to the job name in the Actions UI.
-
-# This prevents workflows from being run twice on PRs
-# ref: https://github.community/t/how-to-trigger-an-action-on-push-or-pull-request-but-not-both/16662
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-  workflow_call:
-
-jobs:
-  lint:
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: ["3.12"]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - uses: pre-commit/action@v3.0.1
-
-  # run our test suite on various combinations of OS / Python / Sphinx version
-  run-pytest:
-    needs: [lint]
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
-        sphinx-version: ["rls"]
-        include:
-          # macos test
-          - os: macos-latest
-            python-version: "3.12"
-            sphinx-version: "rls"
-          # windows test
-          - os: windows-latest
-            python-version: "3.12"
-            sphinx-version: "rls"
-          # old Sphinx test
-          - os: ubuntu-latest
-            python-version: "3.9"
-            sphinx-version: "old"
-          # dev Sphinx test
-          - os: ubuntu-latest
-            python-version: "3.12"
-            sphinx-version: "dev"
-    # needed to cache the browsers for the accessibility tests
-    env:
-      PLAYWRIGHT_BROWSERS_PATH: ${{ github.workspace }}/pw-browsers
-      SPHINX_VERSION: ${{ matrix.sphinx-version }}
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      # waiting for https://github.com/nikeee/setup-pandoc/pull/8
-      # using 12rambau fork until then
-      - uses: 12rambau/setup-pandoc@test
-      - name: Install dependencies
-        # if Sphinx version not specified in matrix, the constraints in the
-        # pyproject.toml file determine Sphinx version
-        shell: bash
-        # setting shell to BASH and using PYTHONUTF8 env var makes the editable
-        # install work on Windows even though there are emoji in our README
-        run: ./tools/github_actions_install.sh test
-      - name: Show installed versions
-        run: python -m pip list
-      - name: Compile MO files
-        run: |
-          pip install nox
-          nox -s compile
-      - name: Run tests
-        run: pytest -m "not a11y" --color=yes --cov --cov-report=xml
-        env:
-          COVERAGE_FILE: ".coverage.${{ matrix.python-version }}.${{ matrix.os }}.${{ matrix.sphinx-version }}"
-      - name: Store coverage file
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ matrix.python-version }}-${{ matrix.os }}-${{ matrix.sphinx-version }}
-          path: .coverage.${{ matrix.python-version }}.${{ matrix.os }}.${{ matrix.sphinx-version }}
-      - name: Upload to Codecov
-        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
-        uses: codecov/codecov-action@v4
-        with:
-          fail_ci_if_error: true
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
-      # note I am setting this on top of the Python cache as I could not find
-      # how to set the hash key on the python one
-      - name: Set up browser cache (for accessibility tests)
-        uses: actions/cache@v4
-        with:
-          path: |
-            ${{ github.workspace }}/pw-browsers
-          key: ${{ runner.os }}-pw-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-pw-
-
-      - name: Run accessibility tests with playwright
-        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
-        run: |
-          nox -s a11y
-        continue-on-error: true
-
-  coverage:
-    name: Collect Coverage
-    runs-on: ubuntu-latest
-    needs: run-pytest
-    # run both on previous step success and failure
-    if: "!cancelled()"
-    permissions:
-      pull-requests: write
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/download-artifact@v4
-        id: download
-        with:
-          pattern: coverage-*
-          merge-multiple: true
-
-      - name: Coverage comment
-        id: coverage_comment
-        uses: py-cov-action/python-coverage-comment-action@v3
-        with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          MERGE_COVERAGE_FILES: true
-
-      - name: Store Pull Request comment to be posted
-        uses: actions/upload-artifact@v4
-        if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true'
-        with:
-          name: python-coverage-comment-action
-          path: python-coverage-comment-action.txt
-
-  # Build our site on the 3 major OSes and check for Sphinx warnings
-  build-site:
-    needs: [lint]
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.12"]
-        sphinx-version: [""]
-        include:
-          - os: ubuntu-latest
-            python-version: "3.9"
-            sphinx-version: "old"
-          # crash with myst parser
-          # will be restored when myst will be dropped from our documentation
-          # - os: ubuntu-latest
-          #   python-version: "3.12"
-          #   sphinx-version: "dev"
-    env:
-      SPHINX_VERSION: ${{ matrix.sphinx-version }}
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      # waiting for https://github.com/nikeee/setup-pandoc/pull/8
-      # using 12rambau fork until then
-      - uses: 12rambau/setup-pandoc@test
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - name: Install dependencies
-        shell: bash
-        run: ./tools/github_actions_install.sh doc
-      - name: Show installed versions
-        run: python -m pip list
-      - name: Build docs
-        run: sphinx-build -b html docs/ docs/_build/html --keep-going -w warnings.txt
-      - name: Check for unexpected Sphinx warnings
-        run: python tests/utils/check_warnings.py
-
-  # Run local Lighthouse audit against built site
-  audit:
-    needs: [build-site]
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: ["3.12"]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - name: Install dependencies
-        run: ./tools/github_actions_install.sh doc
-        shell: bash
-      - name: Show installed versions
-        run: python -m pip list
-      # We want to run the audit on a simplified documentation build so that
-      # the audit results aren't affected by non-theme things like extensions.
-      # Here we copy over just the kitchen sink into an empty docs site with
-      # only the theme loaded so extensions don't play a role in audit scores.
-      - name: Copy kitchen sink to a tiny site and build it
-        run: |
-          mkdir audit/
-          mkdir audit/site
-          cp -r docs/examples/kitchen-sink audit/site/kitchen-sink
-          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > audit/site/index.rst
-          echo 'html_theme = "pydata_sphinx_theme"' > audit/site/conf.py
-          echo '.. toctree::\n   :glob:\n\n   *' >> audit/site/index.rst
-          sphinx-build audit/site audit/_build
-      # The lighthouse audit runs directly on the HTML files, no serving needed
-      - name: Audit with Lighthouse
-        uses: treosh/lighthouse-ci-action@v11
-        with:
-          configPath: ".github/workflows/lighthouserc.json"
-          temporaryPublicStorage: true
-          uploadArtifacts: true
-          runs: 3 # Multiple runs to reduce variance
-
-  # Generate a profile of the code and upload as an artifact
-  profile:
-    needs: [build-site, run-pytest]
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: ["3.12"]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - name: Install dependencies
-        run: ./tools/github_actions_install.sh test nox
-        shell: bash
-      - name: Show installed versions
-        run: python -m pip list
-      - name: Generate a profile
-        run: nox -s profile
-        continue-on-error: true
-      - uses: actions/upload-artifact@v4
-        with:
-          name: profile-results
-          path: profile.svg
diff --git a/docs/community/setup.md b/docs/community/setup.md
index 7e1af82ce..e4f5fd51e 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -47,7 +47,7 @@ To simplify this process, we use a few helper tools:
 - [pandoc](https://pandoc.org/) the universal document converter.
 
 In particular, `tox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
-The rest of this guide focuses on using `nox` to start with a basic environment.
+The rest of this guide focuses on using `tox` to start with a basic environment.
 
 ```{seealso}
 The information on this page covers the basics to get you started, for information about manually compiling assets, see [](topics/manual-dev.md).
@@ -192,7 +192,7 @@ test will fail. If we _expect_ the structure to differ, then delete the file on
 disk and run the test. A new file will be created, and subsequent tests will
 pass.
 
-To run the build tests with `nox`, run the following command:
+To run the build tests with `tox`, run the following command:
 
 ```console
 # this will compile the assets and run the tests (with test coverage)
diff --git a/docs/community/topics/assets.md b/docs/community/topics/assets.md
index c893c6348..848da625a 100644
--- a/docs/community/topics/assets.md
+++ b/docs/community/topics/assets.md
@@ -18,7 +18,7 @@ site after upgrading the theme.
 To compile the assets and bundle them with the theme, run this command:
 
 ```console
-$ nox -s compile
+$ tox -e run compile
 ```
 
 ## Styles (SCSS) and Scripts (JS)
diff --git a/pyproject.toml b/pyproject.toml
index 6e28eb6df..e36b9d8a3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -78,7 +78,7 @@ doc = [
   "colorama",
 ]
 test = ["pytest", "pytest-cov", "pytest-regressions", 'sphinx[test]']
-dev = ["pyyaml", "pre-commit", "nox", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
+dev = ["pyyaml", "pre-commit", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
 a11y = ["pytest-playwright"]
 i18n = ["Babel", "jinja2"]
 
diff --git a/tests/README.md b/tests/README.md
index 6608c4815..ef86e5291 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -1,6 +1,6 @@
 # PyData Sphinx tests
 
-This directory contains the Python tests for the theme. These tests are built with [pytest](https://docs.pytest.org/en/stable/) and are called through `nox`.
+This directory contains the Python tests for the theme. These tests are built with [pytest](https://docs.pytest.org/en/stable/) and are called through `tox`.
 
 - `test_build.py` checks that the static HTML output of the build process conforms
   to various expectations. It builds static HTML pages based on configurations in

From 11343ec242b9588eb8fde0a6955b0d906badadcd Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 May 2024 18:32:54 +0100
Subject: [PATCH 58/73] Rename workflow to best reflect its purpose

---
 .github/workflows/{tests_tox.yml => CI.yml} | 0
 .github/workflows/publish.yml               | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename .github/workflows/{tests_tox.yml => CI.yml} (100%)

diff --git a/.github/workflows/tests_tox.yml b/.github/workflows/CI.yml
similarity index 100%
rename from .github/workflows/tests_tox.yml
rename to .github/workflows/CI.yml
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 93a2a7c33..3678ae616 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -17,7 +17,7 @@ permissions:
 jobs:
   # calls our tests workflow
   tests:
-    uses: ./.github/workflows/tests.yml
+    uses: ./.github/workflows/CI.yml
 
   build-package:
     name: "Build & verify PST package"

From 85650ff11c83d8ca28f3b5c3b8699c905a1aab2e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 10 May 2024 12:59:50 +0100
Subject: [PATCH 59/73] Ensure we do not build pkg before compiling

---
 tools/github_actions_install.sh | 18 ------------------
 tox.ini                         |  2 ++
 2 files changed, 2 insertions(+), 18 deletions(-)
 delete mode 100755 tools/github_actions_install.sh

diff --git a/tools/github_actions_install.sh b/tools/github_actions_install.sh
deleted file mode 100755
index 90e08f1b0..000000000
--- a/tools/github_actions_install.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/bin/bash
-
-# First arg ($1) is the extras_require to install, optional second arg
-# ($2) is an extra dependency (currently just nox on one run)
-set -eo pipefail
-export PYTHONUTF8=1
-if [[ "$SPHINX_VERSION" == "rls" ]]; then
-    SPHINX_INSTALL="sphinx[test]"
-elif [[ "$SPHINX_VERSION" == "dev" ]]; then
-    SPHINX_INSTALL="sphinx[test]@https://codeload.github.com/sphinx-doc/sphinx/zip/refs/heads/master"
-elif [[ "$SPHINX_VERSION" == "old" ]]; then
-    SPHINX_INSTALL="sphinx[test]==6.1.0"
-else  # for the "build site" jobs
-    SPHINX_INSTALL="sphinx<7.3"
-fi
-set -x  # print commands
-python -m pip install --upgrade pip wheel setuptools
-python -m pip install -e .["$1"] ${SPHINX_INSTALL} $2
diff --git a/tox.ini b/tox.ini
index 2c4855af3..ef39b3e99 100644
--- a/tox.ini
+++ b/tox.ini
@@ -23,6 +23,8 @@ extras =
 skip_install = 
     lint: true # do not need to install to lint
     profile-docs: true # avoids issues with py-spy and setting the git repo
+    compile: false
+package = editable
 commands = 
     lint: pre-commit run -a
     compile: stb compile

From a609f3a6283509fb87dccf3380655f6a1a1c2631 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 10 May 2024 13:11:09 +0100
Subject: [PATCH 60/73] Update a11y-pygments test

---
 tests/test_build.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_build.py b/tests/test_build.py
index 3971531ea..241070c75 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -820,7 +820,7 @@ def test_math_header_item(sphinx_build_factory, file_regression) -> None:
         pytest.param(("fake_foo", "fake_bar"), ("#204a87", "#66d9ef"), id="fake"),
         pytest.param(
             ("a11y-high-contrast-light", "a11y-high-contrast-dark"),
-            ("#7928a1", "#dcc6e0"),
+            ("#6730c5", "#dcc6e0"),
             id="real",
         ),
     ),

From 9a51128705d12cf5e5eb505f71881e89e4ce1ec0 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 13 May 2024 13:06:37 +0100
Subject: [PATCH 61/73] Update contrbution docs

---
 .github/actions/set-dev-env/action.yml |  2 ++
 docs/community/setup.md                | 34 ++++++++++++++------------
 docs/community/topics/accessibility.md |  4 +--
 docs/community/topics/manual-dev.md    |  3 ++-
 tests/README.md                        | 12 ++++-----
 tox.ini                                | 11 +++++++--
 6 files changed, 39 insertions(+), 27 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 9a4d1b356..5498eb249 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -21,8 +21,10 @@ runs:
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
         allow-prereleases: true
+
     - run: python -Im pip install tox-uv
       shell: bash
+
     # waiting for https://github.com/nikeee/setup-pandoc/pull/8
     # using 12rambau fork until then
     - name: "Install pandoc 📝"
diff --git a/docs/community/setup.md b/docs/community/setup.md
index e4f5fd51e..119d423ba 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -10,8 +10,8 @@ If you are comfortable with and prefer a more manual setup refer to the [](topic
 We follow a [typical GitHub workflow](https://guides.github.com/introduction/flow/)
 of:
 
-- create a personal fork of this repo
-- create a branch
+- create a personal fork and local clone of this repo
+- create a branch for your contribution
 - open a pull request
 - fix findings of various linters and checks
 - work through code review
@@ -38,7 +38,7 @@ You can clone it for local development like so:
 
 ## Install your tools
 
-Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and JavaScript.
+Building a Sphinx site uses a combination of Python and `Jinja` to manage `HTML`, `scss`, and `JavaScript`.
 To simplify this process, we use a few helper tools:
 
 - [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) compiles web assets in an automated way.
@@ -62,7 +62,7 @@ $ pip install tox
 ```
 
 You can call `tox` from the command line to perform common actions that are needed in building the theme.
-`tox` operates with isolated environments, so each action has its own packages installed in a local directory (`.tox`).
+`tox` operates with isolated environments, so each action has its packages installed in a local directory (`.tox`).
 For common development actions, you'll only need to use `tox` and won't need to set up any other packages.
 
 ### Setup `pre-commit`
@@ -109,7 +109,7 @@ $ tox run -e docs-dev
 
 This will install the necessary dependencies and build the documentation located in the `docs/` folder.
 The generated documentation will be placed in a `docs/_build/html` folder.
-If the docs have already been built, it will only re-build the pages that have been updated.
+If the docs have already been built, it will only rebuild the pages that have been updated.
 You can open one of the HTML files there to preview the documentation locally.
 
 Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with:
@@ -137,7 +137,7 @@ These are then built and bundled with the theme (e.g., `scss` is turned into `cs
 To compile the CSS/JS assets with `tox`, run the following command:
 
 ```console
-$ tox -e run compile
+$ tox run -e compile
 ```
 
 This will compile all assets and place them in the appropriate folder to be used with documentation builds.
@@ -154,7 +154,7 @@ You can combine the above two actions (build the docs and compile JS/CSS assets)
 To run the development server with `tox`, run the following command:
 
 ```console
-$ tox -e run docs-live
+$ tox run -e docs-live
 ```
 
 When working on the theme, making changes to any of these directories:
@@ -196,24 +196,26 @@ To run the build tests with `tox`, run the following command:
 
 ```console
 # this will compile the assets and run the tests (with test coverage)
-$ tox -e run compile,tests
+# note the use of the `-m` flag vs. other commands in this guide
+$ tox run -m tests
 
-# to run the tests without pre-compiling the assets and without coverage (for example if you recently compiled the assets)
-$ tox -e run tests-no-cov
+# to run the tests only without pre-compiling the assets and without coverage (for example if you recently compiled the assets)
+$ tox run -e tests-no-cov
 ```
 
 To run the accessibility checks:
 
 ```console
-$ tox -e run compile,docs, a11y-tests
+# this will compile the assets, build the documentation, and run the accessibility tests
+$ tox run -m a11y
 
 # to run the tests without pre-compiling the assets and without re-building the docs (for example if you recently compiled the assets or built the docs)
-$ tox -e run a11y-tests
+$ tox run -e a11y-tests
 ```
 
-## GitHub codespaces
+## GitHub Codespaces
 
-If you have good internet connectivity and want a temporary set-up, it is often faster to work on PyData Sphinx Theme
-in a Codespaces environment. Once your Codespaces instance is set up, you can run the `tox` commands above to build
-the documentation, compile the assets, and run the tests.
+If you have good internet connectivity and want a temporary set-up, it is often faster to work on the PyData Sphinx Theme
+in a Codespaces environment.
+Once your Codespaces instance is set up, you can run the `tox` commands above to build the documentation, compile the assets, and run the tests.
 For documentation on how to get started with Codespaces, see [the Codespaces documentation](https://docs.github.com/en/codespaces).
diff --git a/docs/community/topics/accessibility.md b/docs/community/topics/accessibility.md
index 4e4485d9c..957b4fcb5 100644
--- a/docs/community/topics/accessibility.md
+++ b/docs/community/topics/accessibility.md
@@ -6,8 +6,8 @@ April-2023: we are currently
 and reporting, so this may change soon.
 ```
 
-In general, accessibility-checking tools can find a limited number of common HTML patterns which
-assistive technology can't help users understand.
+In general, accessibility-checking tools can find a limited number of common HTML patterns that assistive technology
+can't help users understand.
 
 ## Accessibility checks as part of our development process
 
diff --git a/docs/community/topics/manual-dev.md b/docs/community/topics/manual-dev.md
index e2a7ca098..5c952633a 100644
--- a/docs/community/topics/manual-dev.md
+++ b/docs/community/topics/manual-dev.md
@@ -2,7 +2,8 @@
 
 # Set up a manual development environment
 
-If you prefer not to use automation tools like `tox`, or want to have more control over the specific version of packages that you'd like installed, you may set your local development environment manually.
+If you prefer not to use automation tools like `tox`, or want to have more control over the specific version of packages that you'd like installed,
+you may set your local development environment manually.
 
 To do so, follow the instructions on this page.
 
diff --git a/tests/README.md b/tests/README.md
index 48def8d92..32d4017a2 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -18,7 +18,7 @@ This directory contains the Python tests for the theme. These tests are built wi
   In contrast to the build test suite, the accessibility suite checks components as
   they appear in the browser, meaning with any CSS and JavaScript applied. It does
   this by building the PyData Sphinx Theme docs, launching a local server to the
-  docs, then checking the "Kitchen Sink" example pages with
+  docs, and then checking the "Kitchen Sink" example pages with
   [Playwright](https://playwright.dev), a program for developers that allows
   loading and manipulating pages with various browsers, such as Chrome (chromium),
   Firefox (gecko), Safari (WebKit).
@@ -27,17 +27,17 @@ The ["Kitchen Sink" examples](https://pydata-sphinx-theme.readthedocs.io/en/stab
 are taken from [sphinx-themes.org](https://sphinx-themes.org/) and showcase
 components of the PyData Sphinx Theme, such as admonitions, lists, and headings.
 
-## visually debugging the test pages
+## Visually debugging the test pages
 
 It can be useful to build and inspect the test pages in the browser.
 
-By default `nox -s test` will build the html in a temporary directory.
+By default, `tox run -m tests` (or any other `tox` command that runs our tests) will build the HTML in a temporary directory.
 You can change this by using the `PST_TEST_HTML_DIR` environment variable.
 
 For example:
 
-```
-$ PST_TEST_HTML_DIR=./debug-test-theme/ nox -s test
+```bash
+$ PST_TEST_HTML_DIR=./debug-test-theme/ tox run -m tests
 ```
 
-Will save all the generated html in the folders `./debug-test-theme/<test-name>/<site-name>`
+Will save all the generated HTML in the folders `./debug-test-theme/<test-name>/<site-name>`
diff --git a/tox.ini b/tox.ini
index ef39b3e99..5adba8bd9 100644
--- a/tox.ini
+++ b/tox.ini
@@ -2,13 +2,20 @@
 min_version = 4
 # list of environments to run by default with tox run
 # using Python 3.12 as the default, this needs to be kept in line with
-# .github/actions/set-dev-env/action.yml
+# .github/actions/set-dev-env/action.yml (default Python version)
 env_list =
     lint,
     compile,
     py312-docs,
     py312-tests,
-    a11y-tests,
+    a11y-tests
+
+# convenience label for running tests with a given Python version, aimed at 
+# helping contributors run tests locally
+# tox run -m tests
+labels = 
+    tests = compile, py312-tests
+    a11y = compile, py312-docs, a11y-tests
 
 # general tox env configuration
 # these can be run with any py3{9,12} version

From 36ec81ffaef100f6e9a04e4b54d72e683eb6b459 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 19 May 2024 11:53:58 -0400
Subject: [PATCH 62/73] Ensure we always use 80 as coverage treshold

---
 pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index e36b9d8a3..dd2f8d638 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -124,7 +124,7 @@ branch = true
 relative_files = true
 
 [tool.coverage.report]
-fail_under = 60
+fail_under = 80
 show_missing = true
 skip_covered = true
 

From c3d84552eaa3b8f8aec2b5ba470504d64b9d57b4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 19 May 2024 14:08:38 -0400
Subject: [PATCH 63/73] Fix profile step

---
 .github/workflows/CI.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index 91305d1b5..993383369 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -211,7 +211,7 @@ jobs:
           path: htmlcov
         if: ${{ failure() }}
 
-  profile:
+  profiling:
     needs: [build-site, run-pytest]
     runs-on: ubuntu-latest
     steps:
@@ -224,7 +224,7 @@ jobs:
           python-version: "3.11"
       - name: "Run profiling with py-spy 🕵️‍♂️"
         # profiling needs to be run as sudo
-        run: sudo python -Im tox run -e py311-profile-docs -- -o docbuild_profile.svg
+        run: python -m tox run -e py311-profile-docs -- -o docbuild_profile.svg
         continue-on-error: true
       - name: "Upload profiling data to GH artifacts 📤"
         uses: actions/upload-artifact@v4

From 4a59ab5fd3837d7664c235f0b6f81861879019d8 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 23 May 2024 13:54:19 -0600
Subject: [PATCH 64/73] Fix CI - ensure consistency

---
 .github/actions/set-dev-env/action.yml |  2 +-
 .github/workflows/CI.yml               | 14 +++++++-------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml
index 5498eb249..b5398c8eb 100644
--- a/.github/actions/set-dev-env/action.yml
+++ b/.github/actions/set-dev-env/action.yml
@@ -29,4 +29,4 @@ runs:
     # using 12rambau fork until then
     - name: "Install pandoc 📝"
       uses: 12rambau/setup-pandoc@test
-      if: ${{ inputs.pandoc }} == "True"
+      if: ${{ inputs.pandoc }} == true
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index 993383369..79b1f51cc 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -51,7 +51,7 @@ jobs:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: "61"
+            sphinx-version: "6.1"
             # newest Python version with the newest Sphinx version
           - os: ubuntu-latest
             python-version: "3.12"
@@ -69,7 +69,7 @@ jobs:
         uses: ./.github/actions/set-dev-env
         with:
           python-version: ${{ matrix.python-version }}
-          pandoc: "True"
+          pandoc: true
       - name: "Run tests ✅"
         shell: bash
         run: |
@@ -77,7 +77,7 @@ jobs:
           # check if there is a specific Sphinx version to test with
           # example substitution: tox run -e compile,py39-sphinx61-tests
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-tests
+            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx(echo ${{ matrix.sphinx-version }} | tr -d .)-tests
           # if not we use the default version
           # example substitution: tox run -e compile,py39-tests
           else
@@ -121,7 +121,7 @@ jobs:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: "61"
+            sphinx-version: "6.1"
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"
@@ -130,18 +130,18 @@ jobs:
         uses: ./.github/actions/set-dev-env
         with:
           python-version: ${{ matrix.python-version }}
-          pandoc: "True"
+          pandoc: true
       - name: "Build docs and check for warnings 📖"
         shell: bash
         run: |
           # check if there is a specific Sphinx version to build with
           # example substitution: tox run -e docs-py39-sphinx61-docs
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx${{matrix.sphinx-version}}-docs
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx(echo ${{ matrix.sphinx-version }} | tr -d .)-docs
           # build with the default Sphinx version 
           # example substitution: tox run -e docs-py312-docs
           else
-            python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs
           fi
 
   # Run Lighthouse audits on the built site (kitchen-sink only)

From c242b933f7d63d2fd59153c10d8c2d4ff2a95857 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 23 May 2024 20:58:59 +0100
Subject: [PATCH 65/73] Apply suggestions from code review

Co-authored-by: Daniel McCloy <dan@mccloy.info>
---
 pyproject.toml | 2 +-
 tox.ini        | 2 --
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index dd2f8d638..5fb956eae 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -77,7 +77,7 @@ doc = [
   "ipyleaflet",
   "colorama",
 ]
-test = ["pytest", "pytest-cov", "pytest-regressions", 'sphinx[test]']
+test = ["pytest", "pytest-cov", "pytest-regressions", "sphinx[test]"]
 dev = ["pyyaml", "pre-commit", "pydata-sphinx-theme[doc,test]", "tox", "pandoc", "sphinx-theme-builder[cli]"]
 a11y = ["pytest-playwright"]
 i18n = ["Babel", "jinja2"]
diff --git a/tox.ini b/tox.ini
index 5adba8bd9..1caf1352b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -49,8 +49,6 @@ commands =
 # tox run -e compile,py39-sphinx61-tests
 # run tests without coverage
 # tox run -e compile,py39-tests-no-cov
-# skip compilation
-# tox run -e py39-tests 
 [testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
 description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml"
 # need to ensure the package is installed in editable mode

From cb294caf15bcdb062765ad4737b8766bf85478d9 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 23 May 2024 13:59:23 -0600
Subject: [PATCH 66/73] Add nox to devcontainer for now

---
 .devcontainer/devcontainer.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 3a485357e..0a7d0b0ba 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -4,6 +4,7 @@
   "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bullseye",
   "features": {
     "ghcr.io/devcontainers-contrib/features/tox:2": {},
+    "ghcr.io/devcontainers-contrib/features/nox:2": {},
     "ghcr.io/devcontainers-contrib/features/pre-commit:2": {},
     "ghcr.io/rocker-org/devcontainer-features/pandoc:1": {},
     "ghcr.io/devcontainers/features/node:1": {}

From 48c5cdda51080ba5641696271243d7deab42bc19 Mon Sep 17 00:00:00 2001
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: Fri, 24 May 2024 02:21:58 -0700
Subject: [PATCH 67/73] Update .github/workflows/CI.yml

---
 .github/workflows/CI.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index 79b1f51cc..5db40e833 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -77,7 +77,7 @@ jobs:
           # check if there is a specific Sphinx version to test with
           # example substitution: tox run -e compile,py39-sphinx61-tests
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx(echo ${{ matrix.sphinx-version }} | tr -d .)-tests
+            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests
           # if not we use the default version
           # example substitution: tox run -e compile,py39-tests
           else

From e74f1e2136794170c53c1d9ebeb8bc352966a121 Mon Sep 17 00:00:00 2001
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: Fri, 24 May 2024 02:27:23 -0700
Subject: [PATCH 68/73] Update .github/workflows/CI.yml

---
 .github/workflows/CI.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index 5db40e833..f1e3ac6a3 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -137,7 +137,7 @@ jobs:
           # check if there is a specific Sphinx version to build with
           # example substitution: tox run -e docs-py39-sphinx61-docs
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx(echo ${{ matrix.sphinx-version }} | tr -d .)-docs
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-docs
           # build with the default Sphinx version 
           # example substitution: tox run -e docs-py312-docs
           else

From c237a81a2a015e075f687b94c4979b36ea44e3a6 Mon Sep 17 00:00:00 2001
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: Fri, 24 May 2024 05:07:12 -0700
Subject: [PATCH 69/73] Apply suggestions from code review

---
 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index 1caf1352b..76dac86ed 100644
--- a/tox.ini
+++ b/tox.ini
@@ -92,7 +92,7 @@ set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 # keep this in sync across all docs environments
 extras = {[testenv:docs-no-checks]extras}
 deps = 
-    py39-sphinx61-docs: {py39-sphinx61-tests[deps]}
+    py39-sphinx61-docs: py39-sphinx61-tests[deps]
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py

From 325c29d19c4dbf0da031e388af16c6e3368e5bcd Mon Sep 17 00:00:00 2001
From: M Bussonnier <bussonniermatthias@gmail.com>
Date: Fri, 24 May 2024 05:16:13 -0700
Subject: [PATCH 70/73] Apply suggestions from code review

---
 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index 76dac86ed..e878becfc 100644
--- a/tox.ini
+++ b/tox.ini
@@ -92,7 +92,7 @@ set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 # keep this in sync across all docs environments
 extras = {[testenv:docs-no-checks]extras}
 deps = 
-    py39-sphinx61-docs: py39-sphinx61-tests[deps]
+    py39-sphinx61-docs: coverage[toml] sphinx~=6.1.0
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py

From 607f940258e1576c19165aca12336417d1218edf Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 May 2024 09:05:24 -0600
Subject: [PATCH 71/73] Remove coverage from docs

---
 tox.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index e878becfc..6920e004b 100644
--- a/tox.ini
+++ b/tox.ini
@@ -92,7 +92,7 @@ set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
 # keep this in sync across all docs environments
 extras = {[testenv:docs-no-checks]extras}
 deps = 
-    py39-sphinx61-docs: coverage[toml] sphinx~=6.1.0
+    py39-sphinx61-docs: sphinx~=6.1.0
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py

From f5b05074e44d40c3a5257f5dd4e074ecdc9e1ce5 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 May 2024 09:12:42 -0600
Subject: [PATCH 72/73] Add newer Python and ubuntu versions

---
 .github/workflows/CI.yml | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index f1e3ac6a3..db16c3f09 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -44,8 +44,16 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        os: ["ubuntu-latest", "macos-latest", "macos-14", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        # macos-14==latest
+        os:
+          [
+            "ubuntu-latest",
+            "ubuntu-24.04",
+            "macos-14",
+            "macos-13",
+            "windows-latest",
+          ]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
         sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version

From 1043373e07b22a67b80836b7d3eb3c6ed5c8ccc4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 May 2024 09:17:29 -0600
Subject: [PATCH 73/73] Exclude non-supported version

---
 .github/workflows/CI.yml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index db16c3f09..6cfebab9e 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -45,6 +45,7 @@ jobs:
       fail-fast: true
       matrix:
         # macos-14==latest
+        # ubuntu-20.04==latest
         os:
           [
             "ubuntu-latest",
@@ -53,7 +54,7 @@ jobs:
             "macos-13",
             "windows-latest",
           ]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
         sphinx-version: [""]
         include:
           # oldest Python version with the oldest Sphinx version
@@ -69,6 +70,11 @@ jobs:
           # Python 3.9 is not supported on macOS 14 - https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json
           - os: macos-14
             python-version: "3.9"
+          # do not need all the tests so will limit to the latest versions of Python
+          - os: ubuntu-24.04
+            python-version: "3.9"
+          - os: ubuntu-24.04
+            python-version: "3.10"
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"