From 8b31a4c5aeb470e78cfb7163647f82649e81ff7e Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Wed, 25 Jan 2023 16:47:01 -0600
Subject: [PATCH 01/15] refactor workflows

---
 .github/workflows/setup-python.yml |  21 +++++
 .github/workflows/tests.yml        | 128 ++++++++++++++---------------
 pyproject.toml                     |   9 +-
 3 files changed, 83 insertions(+), 75 deletions(-)
 create mode 100644 .github/workflows/setup-python.yml

diff --git a/.github/workflows/setup-python.yml b/.github/workflows/setup-python.yml
new file mode 100644
index 0000000000..48c8c118e0
--- /dev/null
+++ b/.github/workflows/setup-python.yml
@@ -0,0 +1,21 @@
+name: pst-setup-python
+
+# this is a reusable workflow that is called by our other workflows, but should
+# not be run itself.
+
+on:
+  workflow-call:
+    inputs:
+      python-version:
+        required: true
+        type: string
+
+jobs:
+  pst-setup-python:
+    steps:
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ inputs.python-version }}
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
+      - run: python -m pip install --upgrade pip wheel setuptools
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index caddb8e6ea..e70ac6f302 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -11,89 +11,90 @@ on:
 
 env:
   COVERAGE_THRESHOLD: 60
+  DEFAULT_PY: "3.9"
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - name: Setup Python
+        uses: ./.github/workflows/pst-setup-python.yml
         with:
-          python-version: "3.9"
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
+          python-version: ${{ env.DEFAULT_PY }}
       - uses: pre-commit/action@v3.0.0
 
-  tests:
-    runs-on: ${{ matrix.os }}
+  # run our test suite on various combinations of OS / Python / Sphinx version
+  run-pytest:
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11-dev"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
         include:
+          - python-version: "3.7" # legacy
+            sphinx-version: "4.2" # legacy
           - os: macos-latest
-            python-version: "3.9"
+            python-version: ${{ env.DEFAULT_PY }}
           - os: windows-latest
-            python-version: "3.9"
-
+            python-version: ${{ env.DEFAULT_PY }}
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+      - name: Setup Python
+        uses: ./.github/workflows/pst-setup-python.yml
         with:
           python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[coverage]
-          python -m pip list
-
-      - name: Test Sphinx==4.2
-        if: matrix.python-version == '3.7'
-        run: |
-          python -m pip install sphinx==4.2
-          python -m pip list
+        # if Sphinx version not specified in matrix, the constraints in the
+        # pyproject.toml file determine Sphinx version
+        if: false == matrix.sphinx-version
+        run: python -m pip install -e .[test]
+      - name: Install dependencies (legacy Sphinx)
+        # here we override the pyproject.toml constraints to get a specific
+        # Sphinx version
+        if: matrix.sphinx-version
+        run: python -m pip install -e .[test] sphinx==${{ matrix.sphinx-version }}
+      - name: Show installed versions
+        run: python -m pip list
+      - name: Run tests
+        run: pytest --color=yes --cov pydata_sphinx_theme --cov-branch --cov-report term-missing:skip-covered --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
 
-      - name: Build docs to store
+  # Build our site on the 3 major OSes and check for Sphinx warnings
+  build-site:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Python
+        uses: ./.github/workflows/pst-setup-python.yml
+        with:
+          python-version: ${{ env.DEFAULT_PY }}
+      - name: Install dependencies
+        run: python -m pip install -e .[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 that there are no unexpected Sphinx warnings
-        if: matrix.python-version == '3.9'
+      - name: Check for unexpected Sphinx warnings
         run: python tests/check_warnings.py
 
-      - name: Run the tests
-        run: pytest --color=yes --cov pydata_sphinx_theme --cov-branch --cov-report term-missing:skip-covered --cov-fail-under ${{ env.COVERAGE_THRESHOLD }}
-
-      - name: Upload coverage
-        if: ${{ always() }}
-        run: codecov
-
   # Run local Lighthouse audit against built site
   audit:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.8"]
-
     steps:
       - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+      - name: Setup Python
+        uses: ./.github/workflows/pst-setup-python.yml
         with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-
+          python-version: ${{ env.DEFAULT_PY }}
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[coverage]
-
+        run: python -m pip install -e .[test]
+      - 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
@@ -107,7 +108,6 @@ jobs:
           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@v9
@@ -120,29 +120,21 @@ jobs:
   # Generate a profile of the code and upload as an artifact
   profile:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.8"]
-
     steps:
       - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+      - name: Setup Python
+        uses: ./.github/workflows/pst-setup-python.yml
         with:
-          python-version: ${{ matrix.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-
+          python-version: ${{ env.DEFAULT_PY }}
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip wheel setuptools nox
-
+          python -m pip install --upgrade nox
+          python -m pip install -e .[test]
+      - name: Show installed versions
+        run: python -m pip list
       - name: Generate a profile
-        run: |
-          nox -s profile
+        run: nox -s profile
         continue-on-error: true
-
       - uses: actions/upload-artifact@v3
         with:
           name: profile-results
diff --git a/pyproject.toml b/pyproject.toml
index 5a248f33d0..d1caa68892 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -47,8 +47,6 @@ doc = [
   "numpydoc",
   "myst-nb",
   "linkify-it-py",  # for link shortening
-  "pytest",
-  "pytest-regressions",
   "rich",
   "sphinxext-rediraffe",
   "sphinx-sitemap",
@@ -70,19 +68,16 @@ doc = [
 ]
 test = [
   "pytest",
-  "pydata-sphinx-theme[doc]",
-]
-coverage = [
   "pytest-cov",
+  "pytest-regressions",
   "codecov",
   "colorama",
-  "pydata-sphinx-theme[test]",
 ]
 dev = [
   "pyyaml",
   "pre-commit",
   "nox",
-  "pydata-sphinx-theme[coverage]",
+  "pydata-sphinx-theme[doc,test]",
 ]
 
 [project.entry-points]

From 54736c461f223cbadab7374d75930e9c332d51dc Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Wed, 25 Jan 2023 16:55:13 -0600
Subject: [PATCH 02/15] purge ablog from tests

---
 tests/test_build.py | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/tests/test_build.py b/tests/test_build.py
index b3c45a81ee..7fa72c546b 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -779,19 +779,11 @@ def test_deprecated_build_html(sphinx_build_factory, file_regression):
     assert not sphinx_build.html_tree("page2.html").select("div.bd-sidebar-secondary")
 
 
-def test_ablog(sphinx_build_factory):
-    """Ensure that we are over-riding the ABlog default FontAwesome config."""
-
-    confoverrides = {"extensions": ["ablog"]}
-    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
-    assert sphinx_build.app.config.fontawesome_included is True
-
-
 def test_empty_templates(sphinx_build_factory):
     """If a template is empty (e.g., via a config), it should be removed."""
     # When configured to be gone, the template should be removed w/ its parent.
     # ABlog needs to be added so we can test that template rendering works w/ it.
-    confoverrides = {"html_show_sourcelink": False, "extensions": ["ablog"]}
+    confoverrides = {"html_show_sourcelink": False}
     sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
     toc_items = sphinx_build.html_tree("page1.html").select(".toc-item")
     assert not any(ii.select(".tocsection.sourcelink") for ii in toc_items)

From 62216e96f57460fc9bb84cf4b391401fd96b6ac6 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Wed, 25 Jan 2023 17:42:55 -0600
Subject: [PATCH 03/15] can't use workflow-level env vars at job level

---
 .github/workflows/setup-python.yml |  3 ++-
 .github/workflows/tests.yml        | 13 ++-----------
 2 files changed, 4 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/setup-python.yml b/.github/workflows/setup-python.yml
index 48c8c118e0..1dff85dae3 100644
--- a/.github/workflows/setup-python.yml
+++ b/.github/workflows/setup-python.yml
@@ -7,7 +7,8 @@ on:
   workflow-call:
     inputs:
       python-version:
-        required: true
+        required: false
+        default: "3.9"
         type: string
 
 jobs:
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index e70ac6f302..d46359f147 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -11,7 +11,6 @@ on:
 
 env:
   COVERAGE_THRESHOLD: 60
-  DEFAULT_PY: "3.9"
 
 jobs:
   lint:
@@ -20,8 +19,6 @@ jobs:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: ./.github/workflows/pst-setup-python.yml
-        with:
-          python-version: ${{ env.DEFAULT_PY }}
       - uses: pre-commit/action@v3.0.0
 
   # run our test suite on various combinations of OS / Python / Sphinx version
@@ -35,9 +32,9 @@ jobs:
           - python-version: "3.7" # legacy
             sphinx-version: "4.2" # legacy
           - os: macos-latest
-            python-version: ${{ env.DEFAULT_PY }}
+            python-version: "3.9"
           - os: windows-latest
-            python-version: ${{ env.DEFAULT_PY }}
+            python-version: "3.9"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
@@ -71,8 +68,6 @@ jobs:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: ./.github/workflows/pst-setup-python.yml
-        with:
-          python-version: ${{ env.DEFAULT_PY }}
       - name: Install dependencies
         run: python -m pip install -e .[doc]
       - name: Show installed versions
@@ -89,8 +84,6 @@ jobs:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: ./.github/workflows/pst-setup-python.yml
-        with:
-          python-version: ${{ env.DEFAULT_PY }}
       - name: Install dependencies
         run: python -m pip install -e .[test]
       - name: Show installed versions
@@ -124,8 +117,6 @@ jobs:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: ./.github/workflows/pst-setup-python.yml
-        with:
-          python-version: ${{ env.DEFAULT_PY }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade nox

From 9b7c763446dcb0c523f2c04f45133e48fb310f57 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 10:12:49 -0600
Subject: [PATCH 04/15] restore redundancy; DRY is not possible

---
 .github/workflows/setup-python.yml | 22 --------------
 .github/workflows/tests.yml        | 48 +++++++++++++++++++++++-------
 2 files changed, 37 insertions(+), 33 deletions(-)
 delete mode 100644 .github/workflows/setup-python.yml

diff --git a/.github/workflows/setup-python.yml b/.github/workflows/setup-python.yml
deleted file mode 100644
index 1dff85dae3..0000000000
--- a/.github/workflows/setup-python.yml
+++ /dev/null
@@ -1,22 +0,0 @@
-name: pst-setup-python
-
-# this is a reusable workflow that is called by our other workflows, but should
-# not be run itself.
-
-on:
-  workflow-call:
-    inputs:
-      python-version:
-        required: false
-        default: "3.9"
-        type: string
-
-jobs:
-  pst-setup-python:
-    steps:
-      - uses: actions/setup-python@v4
-        with:
-          python-version: ${{ inputs.python-version }}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - run: python -m pip install --upgrade pip wheel setuptools
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index d46359f147..0a421ffde2 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -18,7 +18,11 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
-        uses: ./.github/workflows/pst-setup-python.yml
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
       - uses: pre-commit/action@v3.0.0
 
   # run our test suite on various combinations of OS / Python / Sphinx version
@@ -27,7 +31,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         include:
           - python-version: "3.7" # legacy
             sphinx-version: "4.2" # legacy
@@ -39,19 +43,25 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
-        uses: ./.github/workflows/pst-setup-python.yml
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
         # if Sphinx version not specified in matrix, the constraints in the
         # pyproject.toml file determine Sphinx version
         if: false == matrix.sphinx-version
-        run: python -m pip install -e .[test]
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install -e .[test]
       - name: Install dependencies (legacy Sphinx)
         # here we override the pyproject.toml constraints to get a specific
         # Sphinx version
         if: matrix.sphinx-version
-        run: python -m pip install -e .[test] sphinx==${{ matrix.sphinx-version }}
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install -e .[test] sphinx==${{ matrix.sphinx-version }}
       - name: Show installed versions
         run: python -m pip list
       - name: Run tests
@@ -67,9 +77,15 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
-        uses: ./.github/workflows/pst-setup-python.yml
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: python -m pip install -e .[doc]
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install -e .[doc]
       - name: Show installed versions
         run: python -m pip list
       - name: Build docs
@@ -83,9 +99,15 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
-        uses: ./.github/workflows/pst-setup-python.yml
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: python -m pip install -e .[test]
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          python -m pip install -e .[doc]
       - name: Show installed versions
         run: python -m pip list
       # We want to run the audit on a simplified documentation build so that
@@ -116,10 +138,14 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
-        uses: ./.github/workflows/pst-setup-python.yml
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+          cache: "pip"
+          cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade nox
+          python -m pip install --upgrade pip wheel setuptools nox
           python -m pip install -e .[test]
       - name: Show installed versions
         run: python -m pip list

From 73eb269ff31e1d8a642cf67cae21de363c209bf6 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 10:31:48 -0600
Subject: [PATCH 05/15] fix?

---
 .github/workflows/tests.yml | 3 ++-
 pyproject.toml              | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 0a421ffde2..2908d78ad2 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -31,7 +31,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
         include:
           - python-version: "3.7" # legacy
             sphinx-version: "4.2" # legacy
@@ -83,6 +83,7 @@ jobs:
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
+        shell: bash # avoid using PowerShell
         run: |
           python -m pip install --upgrade pip wheel setuptools
           python -m pip install -e .[doc]
diff --git a/pyproject.toml b/pyproject.toml
index d1caa68892..be331eecda 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -65,13 +65,13 @@ doc = [
   # it at the same time as MyST-NB.
   "nbsphinx",
   "ipyleaflet",
+  "colorama",
 ]
 test = [
   "pytest",
   "pytest-cov",
   "pytest-regressions",
   "codecov",
-  "colorama",
 ]
 dev = [
   "pyyaml",

From 1a1909128b4251f2c2f3fdef7aae717a5d3a3452 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 10:34:30 -0600
Subject: [PATCH 06/15] fix windows? (PYTHONUTF8=1)

---
 .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 2908d78ad2..9b22ea4e68 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -86,7 +86,7 @@ jobs:
         shell: bash # avoid using PowerShell
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[doc]
+          PYTHONUTF8=1 python -m pip install -e .[doc]
       - name: Show installed versions
         run: python -m pip list
       - name: Build docs

From 285024edce0f7961a0bef934775f06196928783a Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 10:39:30 -0600
Subject: [PATCH 07/15] fix profile? (use py 3.8)

---
 .github/workflows/tests.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 9b22ea4e68..94d5e97702 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -20,7 +20,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: "3.8"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - uses: pre-commit/action@v3.0.0
@@ -36,9 +36,9 @@ jobs:
           - python-version: "3.7" # legacy
             sphinx-version: "4.2" # legacy
           - os: macos-latest
-            python-version: "3.9"
+            python-version: "3.8"
           - os: windows-latest
-            python-version: "3.9"
+            python-version: "3.8"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
@@ -79,7 +79,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: "3.8"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -102,7 +102,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: "3.8"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -141,7 +141,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: "3.8"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies

From cad3728fea6704d596844d1346bb5b4ec8af0ad5 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 11:13:37 -0600
Subject: [PATCH 08/15] try setting PYTHONUTF8 var on windows

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

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 94d5e97702..8850c2d757 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -82,11 +82,13 @@ jobs:
           python-version: "3.8"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
+      - name: Allow emoji in README on Windows
+        if: runner.os == 'Windows'
+        run: $env:PYTHONUTF8 = 1
       - name: Install dependencies
-        shell: bash # avoid using PowerShell
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          PYTHONUTF8=1 python -m pip install -e .[doc]
+          python -m pip install -e .[doc]
       - name: Show installed versions
         run: python -m pip list
       - name: Build docs

From e15ab30089a33d13a655169e88f68b8ac75080c8 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 11:34:07 -0600
Subject: [PATCH 09/15] try setting Encoding

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

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 8850c2d757..551e25b3b6 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -84,7 +84,9 @@ jobs:
           cache-dependency-path: "pyproject.toml"
       - name: Allow emoji in README on Windows
         if: runner.os == 'Windows'
-        run: $env:PYTHONUTF8 = 1
+        run: |
+          $OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding
+          $env:PYTHONUTF8 = 1
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip wheel setuptools

From fd7832bbdb922dfefe637164ac466d6c003c54b7 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 11:40:03 -0600
Subject: [PATCH 10/15] try bash+PYTHONUTF8 on Windows

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

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 551e25b3b6..b87c616d8c 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -82,13 +82,10 @@ jobs:
           python-version: "3.8"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
-      - name: Allow emoji in README on Windows
-        if: runner.os == 'Windows'
-        run: |
-          $OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding
-          $env:PYTHONUTF8 = 1
       - name: Install dependencies
+        shell: bash
         run: |
+          export PYTHONUTF8=1
           python -m pip install --upgrade pip wheel setuptools
           python -m pip install -e .[doc]
       - name: Show installed versions

From a5b8dd5d54d0b6a9cab16944da5d9467d2752839 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 11:53:41 -0600
Subject: [PATCH 11/15] add PYTHONUTF8 fix to other windows job too

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

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index b87c616d8c..57277be1e2 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -52,12 +52,16 @@ jobs:
         # if Sphinx version not specified in matrix, the constraints in the
         # pyproject.toml file determine Sphinx version
         if: false == matrix.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: |
+          export PYTHONUTF8=1
           python -m pip install --upgrade pip wheel setuptools
           python -m pip install -e .[test]
       - name: Install dependencies (legacy Sphinx)
         # here we override the pyproject.toml constraints to get a specific
-        # Sphinx version
+        # Sphinx version.
         if: matrix.sphinx-version
         run: |
           python -m pip install --upgrade pip wheel setuptools
@@ -84,6 +88,8 @@ jobs:
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
         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: |
           export PYTHONUTF8=1
           python -m pip install --upgrade pip wheel setuptools

From bf78ba3875015bf87134cf75a68f12a6c672204d Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 12:05:42 -0600
Subject: [PATCH 12/15] fix logo warning?

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 8f9c7c6c3c..6872a43714 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -68,7 +68,7 @@
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
-html_logo = "logo.svg"
+html_logo = "_static/logo.svg"
 html_favicon = "_static/logo.svg"
 html_sourcelink_suffix = ""
 

From 275b51f25050dba6725f63238799bf79aaa5cdff Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 14:20:38 -0600
Subject: [PATCH 13/15] try YAML node anchors

---
 .github/workflows/tests.yml | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 57277be1e2..7787163e2f 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -11,6 +11,8 @@ on:
 
 env:
   COVERAGE_THRESHOLD: 60
+  DEFAULT_PY: &default_py "3.10"
+  # not usable as ${{ env.DEFAULT_PY }} but might work as a YAML node anchor?
 
 jobs:
   lint:
@@ -20,7 +22,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: *default_py
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - uses: pre-commit/action@v3.0.0
@@ -31,14 +33,18 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         include:
-          - python-version: "3.7" # legacy
-            sphinx-version: "4.2" # legacy
+          # legacy test
+          - os: ubuntu-latest
+            python-version: "3.7"
+            sphinx-version: "4.2"
+          # macos test
           - os: macos-latest
-            python-version: "3.8"
+            python-version: *default_py
+          # windows test
           - os: windows-latest
-            python-version: "3.8"
+            python-version: *default_py
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
@@ -83,7 +89,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: *default_py
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -109,7 +115,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: *default_py
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -148,7 +154,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.8"
+          python-version: *default_py
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies

From 861f3ece268224f44a21a9ed647b971108bd759f Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 14:23:32 -0600
Subject: [PATCH 14/15] remove node anchors; use 3.11?

---
 .github/workflows/tests.yml | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 7787163e2f..1efcc6722e 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -11,8 +11,6 @@ on:
 
 env:
   COVERAGE_THRESHOLD: 60
-  DEFAULT_PY: &default_py "3.10"
-  # not usable as ${{ env.DEFAULT_PY }} but might work as a YAML node anchor?
 
 jobs:
   lint:
@@ -22,7 +20,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: *default_py
+          python-version: "3.10"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - uses: pre-commit/action@v3.0.0
@@ -41,10 +39,10 @@ jobs:
             sphinx-version: "4.2"
           # macos test
           - os: macos-latest
-            python-version: *default_py
+            python-version: "3.11"
           # windows test
           - os: windows-latest
-            python-version: *default_py
+            python-version: "3.11"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
@@ -89,7 +87,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: *default_py
+          python-version: "3.11"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -115,7 +113,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: *default_py
+          python-version: "3.11"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -154,7 +152,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: *default_py
+          python-version: "3.11"
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies

From 4f2f93a89ecf764963f6c493efe2122aea040607 Mon Sep 17 00:00:00 2001
From: Daniel McCloy <dan@mccloy.info>
Date: Thu, 26 Jan 2023 14:37:15 -0600
Subject: [PATCH 15/15] use matrix everywhere

---
 .github/workflows/tests.yml | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 1efcc6722e..5d4cf158aa 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -1,5 +1,13 @@
 name: continuous-integration
 
+# 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:
@@ -14,13 +22,17 @@ env:
 
 jobs:
   lint:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.10"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - uses: pre-commit/action@v3.0.0
@@ -81,13 +93,14 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -107,13 +120,17 @@ jobs:
 
   # Run local Lighthouse audit against built site
   audit:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
@@ -146,13 +163,17 @@ jobs:
 
   # Generate a profile of the code and upload as an artifact
   profile:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies