From d7c6d8a735a262293760cc62176fb84a689cdee2 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 16:11:24 +0100 Subject: [PATCH 1/5] :wrench: Update tox.ini - split testenvs based on Python + Sphinx versions --- tox.ini | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/tox.ini b/tox.ini index b675d5a9a..133e74667 100644 --- a/tox.ini +++ b/tox.ini @@ -41,7 +41,6 @@ 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 @@ -49,22 +48,31 @@ commands = # 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 From d84198f6796028bbc57150fb649fbe897e0e1eb3 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 16:25:00 +0100 Subject: [PATCH 2/5] :wrench: Make use of latest Sphinx explicit --- tox.ini | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/tox.ini b/tox.ini index 133e74667..2dfef0c04 100644 --- a/tox.ini +++ b/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 @@ -97,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 From 9f8436b30c5a531a7f61de044d988306ec619b55 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 16:25:47 +0100 Subject: [PATCH 3/5] :construction_worker: Update CI - make sphinx versions explicit and update to Sphinx 6.2 --- .github/workflows/CI.yml | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 0eef947b2..149aa9067 100644 --- a/.github/workflows/CI.yml +++ b/.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: From 61267a89852faf948b9a5034829b92402a495f47 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 16:26:21 +0100 Subject: [PATCH 4/5] Update setup docs - ensure theme is always compiled --- docs/community/setup.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/community/setup.md b/docs/community/setup.md index 9e397bbcb..536c9a2fd 100644 --- a/docs/community/setup.md +++ b/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: From 6468bed9725e3f8ee646fb25f43ec144ff04efd9 Mon Sep 17 00:00:00 2001 From: Tania Allard Date: Mon, 2 Sep 2024 16:29:20 +0100 Subject: [PATCH 5/5] Update pre-release workflow to explicit sphinx version --- .github/workflows/prerelease.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml index f6e84b69b..b08f14273 100644 --- a/.github/workflows/prerelease.yml +++ b/.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