Merge branch 'develop' into pre-commit-ci-update-config

Author: AntObi

.github/workflows/update-changelog.yml

@@ -0,0 +1,58 @@
+name: Update Changelog
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  update-changelog:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Install github_changelog_generator
+        run: |
+          gem install github_changelog_generator
+
+      - name: Generate changelog
+        env:
+          CHANGELOG_GITHUB_TOKEN: ${{ secrets.CHANGELOG_GITHUB_TOKEN }}
+        run: |
+          github_changelog_generator -u WMD-group -p SMACT --token $CHANGELOG_GITHUB_TOKEN --output docs/CHANGELOG.md --exclude-labels dependencies
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Run filter script
+        run: |
+          python dev_scripts/filter_changelog.py docs/CHANGELOG.md
+
+      - name: Run pre-commit hooks
+        uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --files docs/CHANGELOG.md
+
+      - name: Commit and push changes
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git add docs/CHANGELOG.md
+          git commit -m "Update changelog for new release"
+          git push
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -224,4 +224,8 @@ $RECYCLE.BIN/
 
 *.swp
 
-*.bak
+*.bak
+
+# Ignore any files generated by the tutorial notebooks
+docs/tutorials/data/*
+docs/tutorials/*.txt

.pre-commit-config.yaml

@@ -1,3 +1,8 @@
+ci:
+  autoupdate_schedule: monthly
+  skip: [pyright]
+  autofix_commit_msg: pre-commit auto-fixes
+  autoupdate_commit_msg: pre-commit autoupdate
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.9.9

CONTRIBUTING.md

@@ -10,14 +10,72 @@ branches for new work and pull requests for verifying the work.
 The steps for a new piece of work can be summarised as follows:
 
 1. Push up or create [an issue](https://github.com/WMD-group/SMACT/issues).
-2. Create a branch from main, with a sensible name that relates to the issue.
-3. Do the work and commit changes to the branch. Push the branch
+2. Fork the repository, i.e. go to the [`SMACT` repository on GitHub](https://github.com/WMD-group/SMACT) and click the "Fork" button to create a copy of the repository under your own account.
+3. Clone your fork of the repository to your local machine.
+
+   ```bash
+   git clone https://github.com/<your-username>/SMACT.git
+   cd SMACT
+   ```
+
+4. Install the [uv package manager](https://github.com/astral-sh/uv).
+
+   ```bash
+   pip install uv # installs uv package manager
+   ```
+
+5. Create a virtual environment for SMACT.
+
+   Using `uv`:
+
+   ```bash
+   uv create venv # A virtual environment will be created in the current directory
+   source .venv/bin/activate # Activate the virtual environment
+   ```
+
+   N.B. A virtual environment can also be created using [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html) for those more familiar with mamba/conda.
+
+6. Install the package in editable mode with the development, documentation and optional dependencies.
+
+   ```bash
+   uv pip install -e ".[dev,docs,optional]"
+   pre-commit install # Install pre-commit hooks
+   ```
+
+7. Create a branch from master, with a sensible name that relates to the issue.
+
+   ```bash
+   git checkout -b <branch-name> # should be run from the master branch
+   ```
+
+8. Do the work and commit changes to the branch. Push the branch
    regularly to GitHub to make sure no work is accidentally lost.
-4. Write or update unit tests for the code you work on.
-5. When you are finished with the work, ensure that all of the unit
-   tests pass on your own machine.
-6. Open a pull request [on the pull request page](https://github.com/WMD-group/SMACT/pulls).
-7. If nobody acknowledges your pull request promptly, feel free to poke one of the main developers into action.
+
+   ```bash
+   git add <files>
+   git commit -m "A message describing the changes"
+   git push origin <branch-name>
+   ```
+
+9. Write or update unit tests for the code you work on.
+10. When you are finished with the work, ensure that all of the unit tests pass on your own machine by running `pytest -v` in the root directory of the repository.
+
+11. Open a pull request [on the pull request page](https://github.com/WMD-group/SMACT/pulls).
+12. If nobody acknowledges your pull request promptly, feel free to poke one of the main developers into action.
+13. For keeping your repository up to date with the master repository, you can add it as a remote to your local repository.
+
+```bash
+git remote add upstream https://github.com/WMD-group/SMACT.git
+```
+
+Fetch the latest changes from the master branch to keep it up to date (make sure you are on the master branch ).
+
+```bash
+git checkout master
+git pull upstream master
+```
+
+Reminder, `pull` is a combination of `fetch` and `merge`. This could lead to merge conflicts if you have made changes to the master branch.
 
 ## Pull requests
 
@@ -32,14 +90,14 @@ Recommended reading: [How to Write the Perfect Pull Request](https://github.blog
 
 ## Dev requirements
 
-When developing locally, it is recommended to install the python packages in `requirements-dev.txt`.
+When developing locally, it is recommended to install the python packages for development and documentation.
 
 ```bash
-pip install -e ".[dev,docs]"
+pip install -e ".[dev,docs]" # Should be ran from the root of the repository
 ```
 
 This will allow you to run the tests locally with pytest as described in the main README,
-as well as run pre-commit hooks to automatically format python files with isort and black.
+as well as run pre-commit hooks to automatically format python files with [ruff](https://docs.astral.sh/ruff/).
 To install the pre-commit hooks (only needs to be done once):
 
 ```bash
@@ -48,3 +106,12 @@ pre-commit run --all-files # optionally run hooks on all files
 ```
 
 Pre-commit hooks will check all files when you commit changes, automatically fixing any files which are not formatted correctly. Those files will need to be staged again before re-attempting the commit.
+
+To render the documentation locally, you can use the following command:
+
+```bash
+cd docs
+sphinx-build -nW --keep-going -b html . _build/html/
+```
+
+You should then be able to view the documentation by opening `_build/html/index.html` in a web browser. You should inspect the documentation to ensure that it is correctly formatted, any docstrings are present and that the code examples are correct.

dev_scripts/filter_changelog.py

@@ -0,0 +1,34 @@
+"""Remove GitHub Actions bot entries from changelog."""
+
+from __future__ import annotations
+
+import argparse
+import re
+
+
+def remove_github_actions_entries(changelog_path: str) -> None:
+    """Remove GitHub Actions bot entries from the changelog.
+
+    Args:
+        changelog_path: Path to the changelog file.
+    """
+    with open(changelog_path) as file:
+        lines = file.readlines()
+
+    with open(changelog_path, "w") as file:
+        skip = False
+        for line in lines:
+            if re.search(r"\[github-actions\[bot\]\]", line):
+                skip = True
+            elif skip and line.strip() == "":
+                skip = False
+            elif not skip:
+                file.write(line)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Remove GitHub Actions bot entries from changelog.")
+    parser.add_argument("changelog_path", type=str, help="Path to the changelog file")
+    args = parser.parse_args()
+
+    remove_github_actions_entries(args.changelog_path)