MAINT: Test old and new Sphinx versions

.github/workflows/tests.yml

@@ -1,4 +1,7 @@
 name: continuous-integration
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
 
 # README
 # ======
@@ -45,16 +48,26 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.8", "3.9", "3.10", "3.11"]
+        sphinx-version: [""]
         include:
           # macos test
           - os: macos-latest
             python-version: "3.11"
           # windows test
           - os: windows-latest
             python-version: "3.11"
+          # old Sphinx test
+          - os: ubuntu-latest
+            python-version: "3.8"
+            sphinx-version: "old"
+          # dev Sphinx test
+          - os: ubuntu-latest
+            python-version: "3.11"
+            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@v3
@@ -67,21 +80,10 @@ jobs:
       - 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 .[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 --upgrade pip wheel setuptools
-          python -m pip install -e .[test] sphinx==${{ matrix.sphinx-version }}
+        run: tools/github_actions_install.sh test
       - name: Show installed versions
         run: python -m pip list
       - name: Compile MO files
@@ -122,6 +124,16 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.11"]
+        sphinx-version: [""]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.8"
+            sphinx-version: "old"
+          - os: ubuntu-latest
+            python-version: "3.11"
+            sphinx-version: "dev"
+    env:
+      SPHINX_VERSION: ${{ matrix.sphinx-version }}
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v3
@@ -132,9 +144,8 @@ jobs:
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[doc]
+        shell: bash
+        run: ./tools/github_actions_install.sh doc
       - name: Show installed versions
         run: python -m pip list
       - name: Build docs
@@ -159,9 +170,8 @@ jobs:
           cache: "pip"
           cache-dependency-path: "pyproject.toml"
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -e .[doc]
+        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
@@ -203,9 +213,8 @@ jobs:
           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]
+        run: ./tools/github_actions_install.sh test nox
+        shell: bash
       - name: Show installed versions
         run: python -m pip list
       - name: Generate a profile

pyproject.toml

@@ -20,7 +20,7 @@ dynamic = ["version"]
 readme = "README.md"
 requires-python = ">=3.8"
 dependencies = [
-  "sphinx>=4.2",
+  "sphinx>=5.0",
   "beautifulsoup4",
   "docutils!=0.17.0",
   "packaging",

tools/github_actions_install.sh

@@ -0,0 +1,22 @@
+#!/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="git+https://github.com/sphinx-doc/sphinx"
+    if [[ "$1" == "doc" ]]; then
+        # Until they release a new version that undoes the max sphinx pin...
+        DEP_EXTRA="git+https://github.com/executablebooks/MyST-NB git+https://github.com/larsoner/sphinx-sitemap.git@path"
+    fi
+elif [[ "$SPHINX_VERSION" == "old" ]]; then
+    SPHINX_INSTALL="sphinx==5.0"
+else  # not used currently but easy enough
+    SPHINX_INSTALL="sphinx==$SPHINX_VERSION"
+fi
+set -x  # print commands
+python -m pip install --upgrade pip wheel setuptools
+python -m pip install -e .["$1"] ${SPHINX_INSTALL} $2 $DEP_EXTRA