MAINT: Refactor workflows to reduce test dependencies

.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.saobby.my.eu.orgmunity/t/how-to-trigger-an-action-on-push-or-pull-request-but-not-both/16662
 on:
@@ -14,86 +22,123 @@ 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
-      - uses: actions/setup-python@v4
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - 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.8", "3.9", "3.10", "3.11"]
         include:
+          # legacy test
+          - os: ubuntu-latest
+            python-version: "3.7"
+            sphinx-version: "4.2"
+          # macos test
           - os: macos-latest
-            python-version: "3.9"
+            python-version: "3.11"
+          # windows test
           - os: windows-latest
-            python-version: "3.9"
-
+            python-version: "3.11"
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Setup Python
         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
+        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 .[coverage]
-          python -m pip list
-
-      - name: Test Sphinx==4.2
-        if: matrix.python-version == '3.7'
+          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 sphinx==4.2
-          python -m pip list
+          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
+        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]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          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
+          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"]
-
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Setup Python
         uses: actions/setup-python@v4
         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 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
       # 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 +152,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
@@ -119,30 +163,28 @@ jobs:
 
   # Generate a profile of the code and upload as an artifact
   profile:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8"]
-
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
-
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Setup Python
         uses: actions/setup-python@v4
         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 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

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 = ""
 

pyproject.toml

@@ -47,8 +47,6 @@ doc = [
   "numpydoc",
   "myst-nb",
   "linkify-it-py",  # for link shortening
-  "pytest",
-  "pytest-regressions",
   "rich",
   "sphinxext-rediraffe",
   "sphinx-sitemap",
@@ -67,22 +65,19 @@ doc = [
   # it at the same time as MyST-NB.
   "nbsphinx",
   "ipyleaflet",
+  "colorama",
 ]
 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]

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)