Merge pull request #261 from MPoL-dev/quality-of-life

Quality of life improvements

.github/workflows/README.md

@@ -0,0 +1,8 @@
+# MPoL GitHub Actions Workflows
+
+We use GitHub actions to continuously integrate and deploy the MPoL codebase. This document summarizes the intended functionality of each of the workflows.
+
+* `verify-tests-and-docs.yml` runs the unit tests and (if successful) builds (but does not deploy) the documentation to ascertain whether the codebase is in a working state (defined as passing tests on all non-experimental Python versions and a successful documentation build). This workflow is intended to run on every commit to the `main` branch as well as every commit to open pull requests.
+* `docs-build-deploy.yml` builds and deploys the documentation to [GitHub Pages](https://mpol-dev.github.io/MPoL/). This workflow is intended to run on every commit to the `main` branch, to ensure that the currently deployed documentation matches the current state of the source code. Note that if you are merging a PR: you may find that the docs are built twice, once as part of the `verify-tests-and-docs.yml` and then again as part of `docs-build-deploy.yml`. This duplication is OK, since it is designed to support small changes implemented directly on `main` as well as changes introduced through branches and PRs.
+* `pre-release.yml` tries to install the package into Linux, MacOS, and Windows using all supported Python versions. As the name suggests, this is designed to run in anticipation of a release and is triggered by a "draft" release on GitHub.
+* `release.yml` is run when a release is submitted on GitHub. Note that there is no prerequisite for `pre-release.yml` to have run (or passed), but it is a good idea to go through this manually by drafting a release.

.github/workflows/gh_docs.yml → .github/workflows/docs-build-deploy.yml

@@ -1,4 +1,4 @@
-name: gh-pages docs
+name: build and deploy docs
 
 on:
   push:
@@ -7,42 +7,30 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.12'
       - name: Install doc deps
         run: |
           pip install .'[dev]'
       - name: Install Pandoc dependency
         run: |
           sudo apt-get install pandoc
       - name: Set up node
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
       - name: Install mermaid.js dependency
         run: |
           npm install @mermaid-js/mermaid-cli
-      - name: Cache/Restore the .mpol folder cache
-        uses: actions/cache@v3
-        env:
-          cache-name: cache-mpol-dls
-        with:
-          # files are stored in .mpol
-          path: ~/.mpol
-          # the "key" is the hash of the download script
-          key: ${{ hashFiles('docs/download_external_files.py') }}
-      - name: Download large files
-        run: |
-          python3 docs/download_external_files.py
       - name: Build the docs
         run: |
           make -C docs clean
           make -C docs html MERMAID_PATH="../node_modules/.bin/"
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/_build/html

.github/workflows/pre-release.yml

@@ -6,43 +6,17 @@ on:
       - prereleased
 
 jobs:
-  dl_files:
-    runs-on: ubuntu-20.04
-    steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.10"
-      - name: Install package deps
-        run: |
-          pip install .[dev]
-      - name: Cache/Restore the .mpol folder cache
-        uses: actions/cache@v3
-        env:
-          cache-name: cache-mpol-dls
-        with:
-          # files are stored in .mpol
-          path: ~/.mpol
-          # the "key" is the hash of the download script
-          key: ${{ hashFiles('docs/download_external_files.py') }}
-      - name: Download large files
-        run: |
-          python3 docs/download_external_files.py
-
   tests:
-    needs: dl_files # don't bother running if we didn't succeed getting the files
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
-      max-parallel: 4
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
-        os: [ubuntu-20.04, macOS-latest, windows-latest]
+        os: [ubuntu-latest, macOS-latest, windows-latest]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -54,22 +28,6 @@ jobs:
       - name: Install test deps
         run: |
           pip install .[test]
-      - name: Lint with flake8
-        run: |
-          pip install flake8
-          # stop the build if there are Python syntax errors or undefined names
-          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-      - name: Cache/Restore the .mpol folder cache
-        uses: actions/cache@v3
-        env:
-          cache-name: cache-mpol-dls
-        with:
-          # files are stored in .mpol
-          path: ~/.mpol
-          # the "key" is the hash of the download script
-          key: ${{ hashFiles('docs/download_external_files.py') }}
       - name: Run tests with coverage
         run: |
           pytest --cov=mpol

.github/workflows/package.yml → .github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: build and upload pip
+name: build and upload to PyPI
 
 on:
   release:
@@ -7,14 +7,13 @@ on:
 
 jobs:
   deploy:
-    runs-on: ubuntu-20.04
-
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.10
+          python-version: "3.12"
       - name: Install dependencies
         run: |
           pip install --upgrade pip

.github/workflows/tests.yml → .github/workflows/verify-tests-and-docs.yml

@@ -1,4 +1,4 @@
-name: package test
+name: verify tests pass and docs build
 
 on:
   push:
@@ -41,3 +41,21 @@ jobs:
       - name: Run tests with coverage
         run: |
           pytest --cov=mpol
+  docs_build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install doc dependencies
+        run: |
+          pip install .[dev]
+      - name: Install Pandoc dependency
+        run: |
+          sudo apt-get install pandoc
+      - name: Build the docs
+        run: |
+          make -C docs clean
+          make -C docs html

src/mpol/tests.mplstyle

@@ -0,0 +1,4 @@
+image.cmap: inferno
+figure.figsize: 7.1, 5.0
+figure.autolayout: True
+savefig.dpi: 300

test/conftest.py

@@ -8,6 +8,9 @@
 from mpol import coordinates, fourier, gridding, images, utils
 from mpol.__init__ import zenodo_record
 
+import matplotlib.pyplot as plt
+plt.style.use("mpol.tests")
+
 # private variables to this module
 _npz_path = files("mpol.data").joinpath("mock_data.npz")
 _nchan = 4