Merge pull request #112 from IMMM-SFA/dev

fix python versions in docs, auto formatting, add github actions

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: docs
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install pandoc
+        run: |
+          sudo apt-get update -y && sudo apt-get install -y pandoc
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+      - name: Update pip and install python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Build html docs
+        working-directory: 'docs/'
+        run: |
+          make html
+      - name: Commit documentation changes
+        run: |
+          cd docs/build/html
+          git init
+          git add -A
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git commit -m 'deploy' -a || true
+      - name: Push changes to gh-pages
+        uses: ad-m/github-push-action@master
+        with:
+          branch: gh-pages
+          directory: docs/build/html
+          force: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,125 @@
+# This GitHub Action will only push to PyPI if the branch is tagged and then merged to main.
+# Tag the branch with:
+# $ git push REMOTE-NAME TAG-NAME
+
+name: Publish Python to PyPI
+
+on:
+  push:
+    branches:
+        - main
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python distribution to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mosartwmpy
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the Python distribution with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/[email protected]
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    needs:
+    - build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/mosartwmpy
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        verbose: true

.github/workflows/test.yml

@@ -0,0 +1,50 @@
+name: test
+
+on:
+  push:
+  schedule:
+    - cron: '0 8 * * 1'  # Runs every monday at 12am Pacific time
+
+env:
+  HDF5_USE_FILE_LOCKING: 'FALSE'
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: [ '3.9', '3.10', '3.11', '3.12' ]
+        os: [ ubuntu-latest ]
+      fail-fast: false
+
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@master
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+
+      - name: Test and generate coverage report
+        run: |
+            pip install pytest
+            pip install pytest-cov
+            pytest --cov=./ --cov-report=xml
+
+      - uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml # optional
+          name: codecov-umbrella # optional
+          token: ${{ secrets.CODECOV_TOKEN }} # required
+
+      - name: Notify on failure
+        if: failure()  # This step will only run if any previous step fails
+        run: |
+          echo "Build or tests failed. Please check the logs."

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# pre-commit hooks require a user to have installed `pre-commit`:
+#   $ pip install pre-commit
+# Then install the hooks within the repo:
+#   $ cd /PATH/TO/REPO
+#   $ pre-commit install
+
+repos:
+-   repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+        - id: ruff
+          args: [ --fix, --exit-non-zero-on-fix]
+          exclude: .rst
+-   repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+    - id: black
+      args: [--line-length=100]
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: check-ast
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace

CONTRIBUTING.md

@@ -13,11 +13,13 @@ __I found a bug!__
 
 __I fixed a bug!__
 * First of all, thanks!
+* Make sure that you're running the changed files and/or new files through pre-commit by running `$ pip install pre-commit` and `$ pre-commit install` in the mosartwmpy repo. Pre-commit will now automatically check your file formatting when you `$ git commit`.
 * Open a [new Pull Request] with the fix. Ensure the description clearly outlines the bug and the solution. Include the Issue number if applicable.
 
 __I created a new feature!__
 * You're the best!
 * Consider opening a [new Issue] to describe use cases for the new feature. This will offer a platform for discussion and critique.
+* Make sure that you're running the changed files and/or new files through pre-commit by running `$ pip install pre-commit` and `$ pre-commit install` in the mosartwmpy repo. Pre-commit will now automatically check your file formatting when you `$ git commit`.
 * Then, open a [new Pull Request] with clear documentation of the methodology. Be sure to include new unit tests if appropriate.
 
-The [IM3] team truly appreciates and encourages community involvement. We're all in this together! 
+The [IM3] team truly appreciates and encourages community involvement. We're all in this together!

README.md

@@ -2,6 +2,8 @@
 [![codecov](https://codecov.io/gh/IMMM-SFA/mosartwmpy/branch/main/graph/badge.svg?token=IPOY8984MB)](https://codecov.io/gh/IMMM-SFA/mosartwmpy)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.03221/status.svg)](https://doi.org/10.21105/joss.03221)
 [![DOI](https://zenodo.org/badge/312114600.svg)](https://zenodo.org/badge/latestdoi/312114600)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mosartwmpy)](https://pypi.org/project/mosartwmpy/)
+
 
 ## mosartwmpy
 
@@ -10,7 +12,7 @@ For a quick start, check out the [Jupyter notebook tutorial](https://github.com/
 
 ## getting started
 
-Ensure you have Python >= 3.8 available (consider using a [virtual environment](https://github.com/pyenv/pyenv), see the docs [here](https://mosartwmpy.readthedocs.io/en/latest/virtualenv.html) for a brief tutorial), then install `mosartwmpy` with:
+Ensure you have Python v3.9 - v3.12 (consider using a [virtual environment](https://github.com/pyenv/pyenv), see the docs [here](https://mosartwmpy.readthedocs.io/en/latest/virtualenv.html) for a brief tutorial), then install `mosartwmpy` with:
 ```shell
 pip install mosartwmpy
 ```
@@ -135,7 +137,7 @@ Seattle:
 > ```
 
 By default, the output files will still store empty NaN-like values for grid cells outside the subdomain, but
-for even faster simulations and smaller output files set the `grid -> unmask_output` option to `false`. Disabling 
+for even faster simulations and smaller output files set the `grid -> unmask_output` option to `false`. Disabling
 this option causes the output files to only store values for grid cells within the subdomain. These smaller files
 will likely take extra processing to effectively interoperate with other models.