Switch GitHub workflows used in CI from tox environments to nox sessi…

…ons (#2685)

* Add nox sessions for running tests

* Remove tox envs for tests

* Add quotes

* Pass through GH_TOKEN if defined in nox tests session

* Add line to GH_TOKEN in workflow

* Edit changelog: 2685.internal.rst

* Use appropriate API for session.env

* Change API once more

* I remember how dicts work sometimes!

* Add nox session for creating sdists & wheels

* Remove temporary print statements

* Rename session

* Invoke nox session for validating CITATION.cff

* Invoke nox session to `import plasmapy`

* Remove tox-based tests.yml

* Expand note about deprecation of tox.ini

* Put quotes around '3.10' so it doesn't get interpreted as '3.1'

* Fix test_specifier bug

* Add type hints and shuffle things around

* Fix bug

* Finish fixing bug

* Generate names of workflows from matrix

In the past, I've occasionally updated the OS or version of Python in one place,
but not the other. By generating names from the matrix, it'll make it more likely
that there will be self-consistency.  (Also: DRY principle)

* Use run-name instead of name

* Go back to not generating names in matrix of workflows

I wasn't able to get it to work.

* Add missing option for coverage

* Add pytest-cov to pyproject dependencies

* Update subset of requirements files

* Add some requirements files

* Add timeout-minutes for CI

* Update testing guide for Nox

* Minor edits to testing guide

* Update testing guide for nox

* Update README for how to regenerate requirements with nox

* Remove outdated comment

* Update requirements file used in docs

* Edit changelog: 2685.internal.rst

* Clarify use of quotes when invoking Nox sessions

* Incidental updates to coverage settings

* Update cache invalidation

I'm not sure I have the right syntax for hashFiles

* Use all tests requirements files in cache

* Remove type hint which was part of private API

* Ignore .nox & .tox when searching for doc source files

The purpose of this commit is primarily to test if the labeler
GitHub Action is working.

.github/workflows/ci.yml

@@ -13,24 +13,56 @@ on:
 
 env:
   DOC_TROUBLESHOOTING: "Warnings like 'reference target not found' occur when Sphinx tries to interpret text as a Python object, but is unable to do so. This warning can often be fixed by surrounding text in double back ticks instead of single back ticks (e.g., by changing `y` to ``y``) so that it gets formatted as an in-line literal. For more information about addressing documentation build failures, please check out the documentation troubleshooting guide at: https://docs.plasmapy.org/en/latest/contributing/doc_guide.html#troubleshooting"
+  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
 jobs:
 
 
   tests:
     name: ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
 
     strategy:
       fail-fast: false
 
       matrix:
         include:
 
+        - name: Tests, Python 3.12, skip slow tests, doctests, Ubuntu
+          os: ubuntu-latest
+          python: '3.12'
+          nox_session: tests-3.12(skipslow)
+
+        - name: Tests, Python 3.11, with code coverage, macOS
+          os: macos-latest
+          python: '3.11'
+          nox_session: tests-3.11(cov)
+
+        - name: Tests, Python 3.10, lowest direct dependencies, Windows
+          os: windows-latest
+          python: '3.10'
+          nox_session: tests-3.10(lowest-direct)
+
+        - name: Packaging, Python 3.12, Ubuntu
+          os: ubuntu-latest
+          python: '3.12'
+          nox_session: build
+
+        - name: Import PlasmaPy, Python 3.10, Windows
+          os: windows-latest
+          python: '3.10'
+          nox_session: import
+
         - name: Static type checking with mypy, Python 3.12, Ubuntu
           os: ubuntu-latest
           python: '3.12'
-          noxenv: mypy
+          nox_session: mypy
+
+        - name: Validate CITATION.cff
+          os: ubuntu-latest
+          python: '3.12'
+          nox_session: cff
 
     steps:
 
@@ -48,15 +80,26 @@ jobs:
     - name: Install nox and uv
       run: python -m pip install --progress-bar off --upgrade nox uv
 
-    - name: Cache
+    - name: Cache .nox
       uses: actions/cache@v4
       with:
         path: |
           .nox
-        key: ${{ matrix.noxenv }}-${{ runner.os }}-${{ hashFiles('requirements.txt', 'pyproject.toml') }}
+        # Invalidate the cache after changes to pyproject.toml or any
+        # requirements files.
+        key: ${{ matrix.nox_session }}-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'ci_requirements/tests-*.txt') }}
 
     - name: Run tests
-      run: nox -e ${{ matrix.noxenv }}
+      run: nox -e '${{ matrix.nox_session }}'
+
+    - name: Upload coverage reports to Codecov
+      if: ${{ contains(matrix.nox_session, 'cov') }}
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   documentation:
 

changelog/2685.internal.rst

@@ -0,0 +1,2 @@
+Switched the GitHub workflows for running tests from using |tox| environments
+to using |Nox| sessions.

ci_requirements/README.md

@@ -1,14 +1,15 @@
 # Pinned requirements files
 
 [`.github/workflows/update-pinned-reqs.yml`]: ../.github/workflows/update-pinned-reqs.yml
+[Nox]: https://nox.thea.codes/en/stable/
 
-This directory contains pinned requirements files for use by the `tox`
-environments that are used in continuous integration testing. Pinning
-requirements files makes sure that continuous integration tests are
-all run on a set of dependencies that are known to work.
+This directory contains pinned requirements files for use by the [Nox]
+sessions that are used in continuous integration testing. Pinning
+requirements files ensures that continuous integration tests are
+consistently run on a set of dependencies that are known to work.
 
-These requirements files are regenerated weekly via an automated pull
-request created through the GitHub workflow defined in
+These requirements files are regenerated via weekly automated pull
+requests created through the GitHub workflow defined in
 [`.github/workflows/update-pinned-reqs.yml`]. These pull requests help
 us find out when an upstream dependency causes new test failures, and
 usually prevent spontaneous test failures.
@@ -17,14 +18,17 @@ usually prevent spontaneous test failures.
 
 [workflow to update pinned requirements]: https://github.com/PlasmaPy/PlasmaPy/actions/workflows/update-pinned-reqs.yml
 [#2597]: https://github.com/PlasmaPy/PlasmaPy/pull/2597
+[`pyproject.toml`]: https://github.com/PlasmaPy/PlasmaPy/blob/main/pyproject.toml
+
+When the dependencies defined in [`pyproject.toml`] change in a pull
+request, it is necessary to regenerate these requirements files. To
+regenerate the requirements locally, run:
+
+```console
+nox -s requirements
+```
 
 Package maintainers may trigger the [workflow to update pinned
 requirements] through going to that page, selecting _Run workflow_ and
 choosing the `main` branch. This workflow will create a pull request
 (e.g., [#2597]) that updates the files in this directory.
-
-To regenerate the requirements locally, run:
-
-```console
-tox -e requirements
-```

docs/conf.py

@@ -89,6 +89,8 @@
     "**.ipynb_checkpoints",
     "**Untitled*",
     ".DS_Store",
+    ".nox",
+    ".tox",
     "_build",
     "notebooks/langmuir_samples",
     "plasmapy_sphinx",
@@ -99,7 +101,7 @@
 html_extra_path = ["robots.txt"]
 html_favicon = "./_static/icon.ico"
 modindex_common_prefix = ["plasmapy."]
-pygments_style = "default"  # code highlighting style to meet WCAG AA contrast standard
+pygments_style = "default"  # code highlighting to meet WCAG AA contrast standard
 root_doc = "index"
 source_suffix = ".rst"
 templates_path = ["_templates"]