Edits for JOSS reviews

.github/workflows/ci.yml

@@ -37,14 +37,15 @@ jobs:
         with:
           extra_args: --hook-stage manual --all-files
       - name: Run PyLint
-        run: |
-          echo "::add-matcher::$GITHUB_WORKSPACE/.github/matchers/pylint.json"
-          pipx run nox -s pylint
+        run: pipx run nox -s pylint -- --output-format=github
 
   # Run tests and upload to codecov
   test:
     name: Check Python ${{ matrix.python-version }} on ${{ matrix.runs-on }}
     runs-on: ${{ matrix.runs-on }}
+    if: |
+      ${{!startsWith(github.event.head_commit.message, 'docs:') }} ||
+      ${{!startsWith(github.event.head_commit.message, 'style:') }}
     needs: [pre-commit]
     strategy:
       # Otherwise, the workflow would stop if a single job fails. We want to
@@ -97,4 +98,6 @@ jobs:
           --cov-report=term --durations=20
 
       - name: Upload coverage report
-        uses: codecov/[email protected]
+        uses: codecov/[email protected]
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.pre-commit-config.yaml

@@ -1,10 +1,15 @@
 ci:
   autoupdate_commit_msg: "chore: update pre-commit hooks"
   autofix_commit_msg: "style: pre-commit fixes"
+  autoupdate_schedule: quarterly
 
 exclude: |
   (?x)^(
       docs/index.md|
+      docs/install.md|
+      docs/citing.md|
+      docs/overview.md|
+      docs/reference.md|
       docs/api/polartoolkit.rst|
       docs/api/polartoolkit.fetch.rst|
       docs/api/polartoolkit.maps.rst|
@@ -17,8 +22,8 @@ exclude: |
       .github/ISSUE_TEMPLATE/feature_request.md|
       .github/config.yml|
       CONTRIBUTING.md|
-      binder/environment.yml|
       templates/CHANGELOG.md.j2|
+      README.md|
   )$
 
 repos:
@@ -34,7 +39,7 @@ repos:
         additional_dependencies: [black==23.7.0]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.6"
+    rev: "v0.4.2"
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
@@ -44,6 +49,7 @@ repos:
     rev: "v4.5.0"
     hooks:
       - id: check-added-large-files
+        exclude: ^docs/datasets/
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: check-symlinks

CONTRIBUTING.md

@@ -3,7 +3,7 @@
 
 <sub>Adapted from the great contribution guidelines of the [Fatiando a Terra](https://www.fatiando.org/) packages<sub>.
 
-> This document contains some general guidlines to help with contributing to this code. Contributing to a package can be a daunting task, if you want help please reach out on the [GitHub discussions page](https://github.com/mdtanker/polartoolkit/discussions)!
+> This document contains some general guidelines to help with contributing to this code. Contributing to a package can be a daunting task, if you want help please reach out on the [GitHub discussions page](https://github.com/mdtanker/polartoolkit/discussions)!
 
 Any kind of help would be much appreciated. Here are a few ways to contribute:
 * 🐛 Submitting bug reports and feature requests
@@ -40,7 +40,9 @@ contributions.
   - [Code Review](#code-review)
 * [Publish a new release](#publish-a-new-release)
 * [Update the Dependencies](#update-the-dependencies)
+* [Create a conda environment file](#create-a-conda-environment-file)
 * [Set up Binder](#set-up-the-binder-configuration)
+* [Release Checklist](#release-checklist)
 
 ## What Can I Do?
 
@@ -215,12 +217,14 @@ Leave a comment in the PR and we'll help you out.
 
 The Docs are build with `Sphinx` and `Read the Docs`. Due to the above mentioned issues with the included C programs, `Read the Docs (RTD)` can't run the scripts which are part of the docs (i.e. the gallery examples). Because of this the notebooks don't execute on a build, as specified by `execute_notebooks: 'off'` in `_config.yml`. Here is how to run/update the docs on your local machine.
 
-> **Note:** The docs are automatically built on PR's by `RTD`, but it's good practise to build them manually before a PR, to check them for errors.
+> **Note:** The docs are automatically built on PR's by `RTD`, but it's good practice to build them manually before a PR, to check them for errors.
 
 #### Run all .ipynb's to update them
 
     make run_doc_files
 
+If your edits haven't changed any part of the core package, then there is no need to re-run the notebooks. If you changed a notebook, just clear it's contents and re-run that one notebook.
+
 #### Check the build manually (optional)
 
 You can build the docs using, but this will require pandoc to be install on your machine:
@@ -239,14 +243,9 @@ nox -s docs -- --serve
 
 Add, commit, and push all changes to GitHub in a Pull Request, and `RTD` should automatically build the docs.
 
-In each PR, you will see section of the checks for RTD. Click on this to preview the docs for the PR.
+In each PR, you will see section of the checks for `RTD`. Click on this to preview the docs for the PR.
 
-RTD uses the conda environment specified in `env/RTD_env.yml` when it's building.
-To create or update this file based on the necessary dependencies in [docs] of `pyproject.toml`, run the following command:
-
-```
-make RTD_env
-```
+`RTD` uses the conda environment specified in `env/RTD_env.yml` when it's building.
 
 ### Code Review
 
@@ -279,83 +278,48 @@ If you have any trouble, leave a comment in the PR or
 
 This will almost always be done by the developers, but as a guide for them, here are instructions on how to release a new version of the package.
 
-Follow all the above instructions for formating and building the docs
+Follow all the above instructions for formatting. Push your changes to a new or existing Pull Request. Once the automated GitHub Actions run (and pass), merge the PR into the main branch.
 
 ### PyPI (pip)
-Manually increment the version in polartoolkit/__init__.py:
-
-  version = "X.Y.Z"
-
-Build the package locally into the /dist folder:
-
-  make build
-
-Upload the dist files to Test PyPI:
-
-    make test_publish
-
-This should automatically find the TestPyPI username and token from a `.pypirc` file in your home directory.
-
-Make a new environment and activate it:
-
-    make test_pypi_env
-    mamba activate polartoolkit_test_pypi
-
- and run the following, replacing the asterisks with the version number:
-
-    pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ polartoolkit==******
-
-Run a few gallery examples to make sure this env works, then its ready to publish to the real PyPI:
-
-    make publish
-
-Now push the changes to GitHub and make a release with the matching version number.
+PyPI release are made automatically via GitHub actions whenever a pull request is merged.
 
 ### Conda-Forge
-Once the new version is on PyPI, we can update the conda-forge feedstock.
-
-Fork the [conda-forge polartoolkit feedstock](https://github.com/conda-forge/polartoolkit-feedstock) on github:
-
-Clone the fork and checkout a new branch
-
-    git clone https://github.com/mdtanker/polartoolkit-feedstock
-
-    git checkout -b update
-
-Update the `meta.yaml` with the new PyPI version with `grayskull`
-
-  grayskull pypi polartoolkit
-
-Copy the new contents into the old `meta.yaml` file.
-
-Push the changes to GitHub
-
-    git add .
-
-    git commit -m "updating polartoolkit"
-
-    git push origin update
-
-Open a PR on GitHub with the new branch.
+Once the new version is on PyPI, within a few hours a bot will automatically open a new PR in the [PolarToolkit conda-forge feedstock](https://github.com/conda-forge/polartoolkit-feedstock). Go through the checklist on the PR. Most of the time the only actions needs are updated any changes made to the dependencies since the last release. Merge the PR and the new version will be available on conda-forge shortly.
 
 Once the new version is on conda, update the binder .yml file, as below.
 
 ## Update the dependencies
 
 To add or update a dependencies, add it to `pyproject.toml` either under `dependencies` or `optional-dependencies`. This will be included in the next build uploaded to PyPI.
 
-After release a new version on PyPI, we will create a new release on conda-forge, and the new dependencies should automatically be included there.
+If you add a dependency necessary for using the package, make sure to add it to the Binder config file and update the `environment.yml` file in the repository. See below.
 
-If you add a dependency necessary for using the package, make sure to add it to `env/env_test.ylm` and include it in the Binder config file. See below.
+## Create a conda environment file
 
-## Set up the binder configuration
+As a backup options for users experiencing install issues, we include a `environment.yml` file in the repo, which users can download and install from. To update this, run the following commands:
+
+```
+make remove
+make conda_install
+```
 
-To run this package online, Read the Docs will automatically create a Binder instance based on the configuration file `/binder/environment.yml`. This file reflects the latest release on Conda-Forge. Update it with the following commands.
+## Set up the binder configuration
 
-    make conda_install
+To run this package online, Read the Docs will automatically create a Binder instance based on the configuration file `environment.yml` in a separate repository [`Polartoolkit-Binder`](https://github.com/mdtanker/polartoolkit-binder). This file should reflect the latest release on Conda-Forge. To allow all optional features in Binder, we need to manually add optional dependencies to the `environment.yml` file. Also, to use the latest version of PolarToolkit within Binder, makes sure to update its version in the file after each release.
 
-    conda activate polartoolkit
+Once updated, rebuild the Binder environment, look at which package versions Binder used for each specified dependency, and update the environment file with these versions.
 
-    make binder_env
+Now, when submitting a PR, RTD will automatically build the docs and update the Binder environment.
 
-Now, when submitting a PR, RTD will automatically build the docs and update the Binder environment.
+## Release Checklist
+* re-run any relevant notebooks
+* check docs are building correctly using the GitHub actions link within the PR
+* merge the  PR
+* wait for `PyPI` to publish the new version [here](https://pypi.python.org/pypi/polartoolkit)
+* wait for a PR to be opened in the [feedstock](https://github.com/conda-forge/polartoolkit-feedstock)
+* update any changed dependencies in the feedstock PR and merge
+* wait for `conda` to publish the new version [here](https://anaconda.org/conda-forge/polartoolkit)
+* update backup `env/environment.yml`
+* update polartoolkit version in `environment.yml` in [PolarToolkit-Binder repo](https://github.com/mdtanker/polartoolkit-binder/blob/main/environment.yml)
+* test `PyPI` version with `make install_test` and `make test`
+* test `conda` version with `make conda_install` and `make test`

Makefile

@@ -2,27 +2,47 @@
 PROJECT=polartoolkit
 STYLE_CHECK_FILES=.
 
-create:
-	mamba create --name $(PROJECT) --yes --force pygmt geopandas python=3.11
+####
+####
+# install commands
+####
+####
 
-create_test_env:
-	mamba create --name test --yes python=3.11
+create:
+	mamba create --name $(PROJECT) --yes --force --channel conda-forge pygmt geopandas python=3.11
 
 install:
 	pip install -e .[all]
 
 install_test:
-	pip install polartoolkit[all]
+	pip install $(PROJECT)[all]
 
 remove:
 	mamba remove --name $(PROJECT) --all
 
+conda_install:
+	mamba create --name $(PROJECT) --yes --force --channel conda-forge $(PROJECT)
+
+conda_export:
+	mamba env export --name $(PROJECT) --channel conda-forge --file env/environment.yml
+####
+####
+# test commands
+####
+####
+
 test:
 	pytest -m "not earthdata and not issue and not fetch"
 
 test_fetch:
 	pytest -s -m fetch #-rp
 
+####
+####
+# style commands
+####
+####
+
 format:
 	ruff format $(STYLE_CHECK_FILES)
 
@@ -33,12 +53,19 @@ lint:
 	pre-commit run --all-files
 
 pylint:
-	pylint polartoolkit
+	pylint $(PROJECT)
 
 style: format check lint pylint
 
 mypy:
-	mypy src/polartoolkit
+	mypy src/$(PROJECT)
+
+
+####
+####
+# chore commands
+####
+####
 
 release_check:
 	semantic-release --noop version
@@ -52,6 +79,13 @@ license-add:
 license-check:
 	python tools/license_notice.py --check
 
+
+####
+####
+# doc commands
+####
+####
+
 run_gallery:
 	jupyter nbconvert --ExecutePreprocessor.allow_errors=True --execute --inplace docs/gallery/*.ipynb
 
@@ -63,31 +97,3 @@ run_doc_files:
 	jupyter nbconvert --ExecutePreprocessor.allow_errors=True --execute --inplace docs/*/*.ipynb
 
 run_notebooks: run_gallery run_tutorials run_doc_files
-
-# install with conda
-conda_install:
-	mamba create --name polartoolkit --yes --force polartoolkit
-
-# create binder yml
-binder_env:
-	mamba env export --name polartoolkit --no-builds > binder/environment.yml
-
-# create ReadTheDocs yml
-RTD_env:
-	mamba remove --name RTD_env --all --yes
-	mamba create --name RTD_env --yes --force python==3.11 pygmt>=0.10.0
-	mamba env export --name RTD_env --no-builds --from-history > env/RTD_env.yml
-	# delete last line
-	sed -i '$$d' env/RTD_env.yml
-	# add pip and install local package
-	sed -i '$$a\  - pip\n  - pip:\n    - ../.[docs]' env/RTD_env.yml
-
-# create testing yml
-testing_env:
-	mamba remove --name testing_env --all --yes
-	mamba create --name testing_env --yes --force pygmt
-	mamba env export --name testing_env --no-builds --from-history > env/testing_env.yml
-	# delete last line
-	sed -i '$$d' env/testing_env.yml
-	# add pip and install local package
-	sed -i '$$a\  - pip\n  - pip:\n    - ../.[test]' env/testing_env.yml