WIP - Explicit installation of Sphinx versions

.github/workflows/CI.yml

@@ -44,11 +44,15 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
         sphinx-version: [""]
         include:
-          # oldest Python version with the oldest Sphinx version
+          # oldest Python version with the oldest (major) Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: "6.1"
-            # newest Python version with the newest Sphinx version
+            sphinx-version: "6.2"
+          # newest Python with the latest released Sphinx version
+          - os: ubuntu-latest
+            python-version: "3.12"
+            sphinx-version: "latest"
+          # newest Python version with the development Sphinx version
           - os: ubuntu-latest
             python-version: "3.12"
             # Sphinx HEAD
@@ -79,10 +83,12 @@ jobs:
           # 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
-          # if not we use the default version
-          # example substitution: tox run -e compile,py39-tests
+
+          # if there is no specified Sphinx version, run with the default;
+          # that is the latest for the corresponding Python version
+          # example substitution: tox run -e compile,py39-tests-sphinxlatest
           else
-            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
+            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinxlatest-tests
           fi
       - name: "Upload coverage data to GH artifacts 📤"
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
@@ -121,7 +127,11 @@ jobs:
           # oldest Python version with the oldest Sphinx version
           - os: ubuntu-latest
             python-version: "3.9"
-            sphinx-version: "6.1"
+            sphinx-version: "6.2"
+          # newest Python version with the development Sphinx version
+          - os: ubuntu-latest
+            python-version: "3.12"
+            sphinx-version: "dev"
     runs-on: ${{ matrix.os }}
     steps:
       - name: "Checkout repository 🛎"
@@ -139,10 +149,11 @@ jobs:
           # example substitution: tox run -e 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
-          # build with the default Sphinx version
-          # example substitution: tox run -e py312-docs
+
+          # build with the default Sphinx version (latest for the corresponding Python version)
+          # example substitution: tox run -e py312-sphinxlatest-docs
           else
-            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs
+            python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinxlatest-docs
           fi
 
   # Run Lighthouse audits on the built site (kitchen-sink only)
@@ -178,7 +189,7 @@ jobs:
           runs: 3 # Multiple runs to reduce variance
 
   coverage:
-    name: "check coverage"
+    name: "Check coverage"
     needs: run-pytest
     runs-on: ubuntu-latest
     permissions:

.github/workflows/prerelease.yml

@@ -32,12 +32,12 @@ jobs:
           python -Im pip install --upgrade pip wheel setuptools
       - 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
+          # example substitution: tox run -e docs-py312-sphinxlatest-docs
+          python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-sphinxlatest-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
+          python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinxlatest-tests
           echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV
 
       # If either the docs build or the tests resulted in an error, create an issue to note it

docs/community/setup.md

@@ -223,9 +223,6 @@ To run the build tests with `tox`, run the following command:
 # this will compile the assets and run the tests (with test coverage)
 # note the use of the `-m` flag vs. other commands in this guide
 $ tox run -m tests
-
-# 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:

tox.ini

@@ -14,7 +14,7 @@ env_list =
 # helping contributors run tests locally
 # tox run -m tests
 labels = 
-    tests = compile, py312-tests
+    tests = compile, py312-sphinxlatest-tests
     a11y = compile, py312-docs, a11y-tests
 
 # general tox env configuration
@@ -41,30 +41,38 @@ 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), 
 # tox run -e compile,py39-tests 
 # if you want to skip the assets compilation step you can run the tests without 
 #`compile`, for example:
 # tox run -e 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
-[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"
+# tox run -e compile,py310-sphinxdev-tests
+# all possible combinations are listed below, and are based on the Python
+# version supported by the Sphinx version (expanding here because it is easier to read)
+#py3{9,10}-sphinx{61,62,70,71}-tests,
+#py3{10,11,12}-sphinx{latest,dev}-tests,
+#py3{9,10,11,12}-sphinx{72,73,74,80}-tests,
+[testenv:py3{9,10}-sphinx{61,62,70,71}-tests,py3{9,10,11,12}-sphinx{72,73,74,80}-tests,py3{10,11,12}-sphinx{latest,dev}-tests]
+description = "Run tests with a specific Sphinx version"
 # need to ensure the package is installed in editable mode
 package = editable
 extras =
-    test # install dependencies - defined in pyproject.toml
+    test # test dependencies - defined in pyproject.toml
 deps = 
     coverage[toml]
-    py39-sphinx61-tests: sphinx~=6.1.0
-    py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
+    sphinx61: Sphinx>=6.1,<6.2
+    sphinx62: Sphinx>=6.2,<6.3
+    sphinx70: Sphinx>=7.0,<7.1
+    sphinx71: Sphinx>=7.1,<7.2
+    sphinx72: Sphinx>=7.2,<7.3
+    sphinx80: Sphinx>=8.0,<8.1
+    sphinxlatest: Sphinx
+    sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 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-no-cov: pytest -m "not a11y" {posargs}
+    coverage run -m pytest -m "not a11y" {posargs}
 
 # run accessibility tests with Playwright and axe-core
 # compiling the assets is needed before running the tests
@@ -89,15 +97,17 @@ commands =
 # 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]
+# tox run -e py39-sphinx62-docs
+[testenv:py3{9,12}-sphinx{62,latest,dev}-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
 # keep this in sync across all docs environments
 extras = {[testenv:docs-no-checks]extras}
 deps = 
-    py39-sphinx61-docs: sphinx~=6.1.0
+    sphinx62: Sphinx>=6.2,<6.3
+    sphinxlatest: Sphinx
+    sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
 commands =
     sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs}
     python tests/utils/check_warnings.py