Update template

.github/pull_request_template.md

@@ -23,21 +23,22 @@
 ## Checklist ✅
 
 - [ ] I have run and tested my changes locally
-- [ ] I have limited this PR to less than 1000 lines of code change (if not, explain why)
+- [ ] I have limited this PR to less than 1000 lines of code change (if not, explain
+  why)
 - [ ] I have updated/added tests to cover my changes (if applicable)
 - [ ] I have updated/added requirements to cover my changes (if applicable)
 - [ ] I have run linting and formatting on any code changes (if applicable)
 - [ ] I have updated the documentation (README, etc.) accordingly
 
 ## Reviewer Emoji Legend
 
-|     |         `:code:`          | Meaning                                                                                                                                                                                                                                         |
-| :-: | :-----------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 😃👍💯 | `:smiley:` `:+1:` `:100:` | I like this... <br /><br /> ...and I want the author to know it! This is a way to highlight positive parts of a code review.                                                                                                                    |
-| ⭐⭐⭐ |  `:star: :star: :star:`   | Important to fix before PR can be approved... <br /><br /> And I am providing reasons why it needs to be addressed as well as suggested improvements.                                                                                           |
-| ⭐⭐  |      `:star: :star:`      | Important to fix but non-blocking for PR approval... <br /><br /> And I am providing suggestions where it could be improved either in this PR or later.                                                                                         |
-|  ⭐  |         `:star:`          | Give this some thought but non-blocking for PR approval... <br /><br /> ...and consider this a suggestion, not a requirement.                                                                                                                   |
-|  ❓  |       `:question:`        | I have a question. <br /><br /> This should be a fully formed question with sufficient information and context that requires a response.                                                                                                        |
-|  📝  |         `:memo:`          | This is an explanatory note, fun fact, or relevant commentary that does not require any action.                                                                                                                                                 |
-|  ⛏  |         `:pick:`          | This is a nitpick. <br /><br /> This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter |
-| ♻️  |        `:recycle:`        | Suggestion for refactoring. <br /><br /> Should include enough context to be actionable and not be considered a nitpick.                                                                                                                        |
+  |        | `:code:`                  | Meaning                                                                                                                                                                                                                                         |
+  | :----: | :-----------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | 😃👍💯 | `:smiley:` `:+1:` `:100:` | I like this... <br /><br /> ...and I want the author to know it! This is a way to highlight positive parts of a code review.                                                                                                                    |
+  | ⭐⭐⭐ |  `:star: :star: :star:`   | Important to fix before PR can be approved... <br /><br /> And I am providing reasons why it needs to be addressed as well as suggested improvements.                                                                                           |
+  |  ⭐⭐  |      `:star: :star:`      | Important to fix but non-blocking for PR approval... <br /><br /> And I am providing suggestions where it could be improved either in this PR or later.                                                                                         |
+  |   ⭐   |         `:star:`          | Give this some thought but non-blocking for PR approval... <br /><br /> ...and consider this a suggestion, not a requirement.                                                                                                                   |
+  |   ❓   |       `:question:`        | I have a question. <br /><br /> This should be a fully formed question with sufficient information and context that requires a response.                                                                                                        |
+  |   📝   |         `:memo:`          | This is an explanatory note, fun fact, or relevant commentary that does not require any action.                                                                                                                                                 |
+  |   ⛏    |         `:pick:`          | This is a nitpick. <br /><br /> This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter |
+  |   ♻️   |        `:recycle:`        | Suggestion for refactoring. <br /><br /> Should include enough context to be actionable and not be considered a nitpick.                                                                                                                        |

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Sync uv
+        run: uv sync --locked
+      - uses: pre-commit/action@v3.0.1
+
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Sync uv
+        run: uv sync --locked
+      - name: Run tests
+        run: uv run pytest

.gitignore

@@ -71,6 +71,10 @@ instance/
 # Sphinx documentation
 docs/_build/
 
+# Quarto
+/docs/_site/
+/docs/.quarto/
+
 # PyBuilder
 .pybuilder/
 target/

.pre-commit-config.yaml

@@ -22,10 +22,11 @@ repos:
     hooks:
       - id: codespell
 
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.45.0
+  - repo: https://github.com/jolars/panache-pre-commit
+    rev: v3.0.0
     hooks:
-      - id: markdownlint-fix
+      - id: panache-format
+      - id: panache-lint
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.12.2

.vscode/extensions.json

@@ -5,7 +5,7 @@
         "ms-python.vscode-python-envs",
         "charliermarsh.ruff",
         "github.vscode-pull-request-github",
-        "davidanson.vscode-markdownlint",
+        "jolars.panache",
         "quarto.quarto",
         "skellock.just",
         "yzhang.markdown-all-in-one",

Justfile

@@ -1,97 +1,144 @@
-# Set the shell to use
-# set shell := ["nu", "-c"]
 # Set shell for Windows
-
 set windows-shell := ["powershell.exe", "-NoLogo", "-Command"]
 
-# Set path to virtual environment's python
+# List available recipes
+[private]
+default:
+    @just --list
 
-venv_dir := ".venv"
-python := venv_dir + if os_family() == "windows" { "/Scripts/python.exe" } else { "/bin/python3" }
+# ---------------------------------------------------------------------------
+# Setup
+# ---------------------------------------------------------------------------
 
-# Display system information
-system-info:
-    @echo "CPU architecture: {{ arch() }}"
-    @echo "Operating system type: {{ os_family() }}"
-    @echo "Operating system: {{ os() }}"
+# Install required system tools, then build the environment
+[group("setup")]
+get-started: pre-install venv
 
-# Clean venv
-clean:
-    rm -rf .venv
+# Install required system tools
+[group("setup")]
+[windows]
+pre-install:
+    winget install astral-sh.uv GitHub.cli
 
-# Setup environment
-get-started: pre-install venv
+[group("setup")]
+[linux]
+pre-install:
+    brew install uv gh
 
-# Update project software versions in requirements
-update-reqs:
-    uv lock
-    pre-commit autoupdate
+[group("setup")]
+[macos]
+pre-install:
+    brew install uv gh
 
-# create virtual environment
+# Create/update the virtual environment and install git hooks
+[group("setup")]
 venv:
     uv sync
-    uv tool install pre-commit
     uv run pre-commit install
 
-activate-venv:
-    uv shell
+# Upgrade locked dependencies and pre-commit hooks
+[group("setup")]
+update-reqs:
+    uv lock --upgrade
+    uv sync
+    uv run pre-commit autoupdate
+
+# Remove the virtual environment
+[group("setup")]
+[unix]
+clean:
+    rm -rf .venv
+
+# Remove the virtual environment
+[group("setup")]
+[windows]
+clean:
+    if (Test-Path .venv) { Remove-Item -Recurse -Force .venv }
+
+# Display system information
+[group("setup")]
+system-info:
+    @echo "CPU architecture: {{ arch() }}"
+    @echo "Operating system type: {{ os_family() }}"
+    @echo "Operating system: {{ os() }}"
+
+# ---------------------------------------------------------------------------
+# Develop
+# ---------------------------------------------------------------------------
 
-# launch jupyter lab
+# Launch Jupyter Lab
+[group("develop")]
 lab:
     uv run jupyter lab
 
-# Preview the quarto project
+# Preview the Quarto docs site
+[group("develop")]
 preview-docs:
-    quarto preview
+    quarto preview docs
 
-# Build the quarto project
+# Render the Quarto docs site
+[group("develop")]
 build-docs:
-    quarto render
+    quarto render docs
+
+# ---------------------------------------------------------------------------
+# Check
+# ---------------------------------------------------------------------------
 
 # Lint python code
+[group("check")]
 lint-py:
-    uv run ruff check
+    uv run ruff check .
 
 # Format python code
-fmt-python:
-    uv run ruff format
-
-# Format a single python file, "f"
-fmt-py f:
-    uv run ruff format {{ f }}
+[group("check")]
+fmt-py *paths=".":
+    uv run ruff format {{ paths }}
 
-# Lint sql scripts
+# Lint sql scripts (auto-fix)
+[group("check")]
 lint-sql:
-    uv run sqlfluff fix --dialect duckdb
-
-# Format all markdown and config files
-fmt-markdown:
-    uv run mdformat .
-
-# Format a single markdown file, "f"
-fmt-md f:
-    uv run mdformat {{ f }}
-
-# Check format of all markdown files
-fmt-check-markdown:
-    uv run mdformat --check .
-
-fmt-all: lint-py fmt-python lint-sql fmt-markdown
-
-# Run pre-commit hooks
+    uv run sqlfluff fix --dialect duckdb .
+
+# Format markdown and Quarto files
+[group("check")]
+fmt-md *paths=".":
+    uv run panache format {{ paths }}
+
+# Check markdown/Quarto formatting without changing files
+[group("check")]
+fmt-check-md:
+    uv run panache format --check .
+
+# Lint markdown and Quarto files
+[group("check")]
+lint-md:
+    uv run panache lint .
+
+# Run the test suite
+[group("check")]
+test *args:
+    uv run pytest {{ args }}
+
+# Run the test suite with coverage
+[group("check")]
+test-cov:
+    uv run pytest --cov=project_name --cov-report=term-missing
+
+# Format everything
+[group("check")]
+fmt-all: fmt-py fmt-md
+
+# Run all pre-commit hooks against all files
+[group("check")]
 pre-commit-run:
-    pre-commit run
+    uv run pre-commit run --all-files
 
-[windows]
-pre-install:
-    winget install Casey.Just astral-sh.uv GitHub.cli Posit.Quarto OpenJS.NodeJS
-    npm install -g markdownlint-cli
+# Run every check (lint, format check, tests, hooks)
+[group("check")]
+check-all: lint-py lint-md fmt-check-md test pre-commit-run
 
-[linux]
-pre-install:
-    brew install just uv gh markdownlint-cli
-
-[macos]
-pre-install:
-    brew install just uv gh markdownlint-cli
-    brew install --cask quarto
+# Backwards-compatible aliases
+alias fmt-python := fmt-py
+alias fmt-markdown := fmt-md
+alias fmt-check-markdown := fmt-check-md