Merge branch 'main' into joss_paper

Updating joss branch with the many changes made to main in the last year.

.coveragerc

@@ -1,7 +1,6 @@
 [run]
 omit =
     venv/*
-    src/mpol/spheroidal_gridding.py
 relative_files = True
 
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -10,7 +10,7 @@ assignees: ''
 **Describe the bug**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
+**To reproduce**
 Steps to reproduce the behavior:
 
 **Expected behavior**
@@ -21,8 +21,11 @@ If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
  - OS: [e.g. Linux + distro, MacOS, Windows]
- - Python Version
- - MPoL Version (`$python -c "import mpol; print(mpol.__version__)"`
+ - Python version
+ - MPoL version (`$python -c "import mpol; print(mpol.__version__)"`
+
+**Suggested fix**
+If you have a suggestion for how to fix the bug, please explain.
 
 **Additional context**
 Add any other context about the problem here.

.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/docs-build-deploy.yml

@@ -0,0 +1,36 @@
+name: build and deploy docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  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 deps
+        run: |
+          pip install .'[dev]'
+      - name: Install Pandoc dependency
+        run: |
+          sudo apt-get install pandoc
+      - name: Set up node
+        uses: actions/setup-node@v4
+      - name: Install mermaid.js dependency
+        run: |
+          npm install @mermaid-js/mermaid-cli
+      - 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@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.8
-      - 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.8", "3.9", "3.10"]
-        os: [ubuntu-20.04, macOS-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+        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.8
+          python-version: "3.12"
       - name: Install dependencies
         run: |
           pip install --upgrade pip