Modernize packaging, CI, and documentation

.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-suffix: test-${{ matrix.python-version }}
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libgl1 libxkbcommon-x11-0
+      - run: uv sync --extra dev
+      - run: uv run --no-sync coverage run -m pytest -q
+      - run: uv run --no-sync coverage report
+      - name: Smoke test CLI and example
+        run: |
+          uv run --no-sync pyfem --help
+          uv run --no-sync pyfem --version
+          mkdir -p "$RUNNER_TEMP/pyfem-smoke"
+          cp examples/ch02/PatchTest8.pro examples/ch02/PatchTest8.dat "$RUNNER_TEMP/pyfem-smoke/"
+          cd "$RUNNER_TEMP/pyfem-smoke"
+          "$GITHUB_WORKSPACE/.venv/bin/pyfem" PatchTest8.pro
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-suffix: build
+      - run: uv build
+      - name: Verify wheel installs
+        run: |
+          uv venv "$RUNNER_TEMP/pyfem-wheel-check"
+          uv pip install --python "$RUNNER_TEMP/pyfem-wheel-check" dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/pyfem-wheel-check/bin/python" -c "import pyfem; from importlib.metadata import version; assert pyfem.__version__ == version('pyfem')"
+          "$RUNNER_TEMP/pyfem-wheel-check/bin/pyfem" --help
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-suffix: docs
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libgl1
+      - run: uv sync --extra docs
+      - run: uv run --no-sync sphinx-build -b html doc doc/_build/html
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: doc/_build/html
+
+  deploy-docs:
+    name: Deploy documentation
+    needs: docs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: pages-${{ github.ref }}
+      cancel-in-progress: false
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v5
+        id: deployment

.gitignore

@@ -124,6 +124,7 @@ celerybeat-schedule
 # Environments
 .env
 .venv
+uv.lock
 env/
 venv/
 ENV/

.readthedocs.yaml

@@ -1,35 +1,26 @@
 # Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# https://docs.readthedocs.com/platform/stable/config-file/v2.html
 
 version: 2
 
-# Build documentation in the doc/ directory with Sphinx
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  apt_packages:
+    - libgl1
+
 sphinx:
   configuration: doc/conf.py
   fail_on_warning: false
 
-# Build environment
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.11"
-  jobs:
-    post_checkout:
-      # Generate API documentation
-      - echo "Generating API documentation..."
-
-# Python dependencies
 python:
   install:
-    # Install documentation requirements
-    - requirements: doc/requirements.txt
-    # Install the package itself
-    - method: pip
-      path: .
-      extra_requirements:
+    - method: uv
+      command: sync
+      extras:
         - docs
 
-# Formats to build (PDF, EPUB, etc.)
 formats:
   - pdf
   - epub

CONTRIBUTING.md

@@ -63,29 +63,37 @@ git clone https://github.com/<your-username>/PyFEM.git
 cd PyFEM
 ```
 
-Create and activate a virtual environment:
+Use Python 3.10 or newer.
+
+For local development, use [uv](https://docs.astral.sh/uv/) to create a virtual
+environment and install the test tools:
 
 ```bash
-python -m venv pyfem-env
+uv sync --extra dev
+uv run --no-sync pytest -q
 ```
 
-On Linux or macOS:
+To include the optional GUI, add `--extra gui` to `uv sync`.
+
+If you prefer pip, create and activate a virtual environment on Linux or macOS:
 
 ```bash
+python -m venv pyfem-env
 source pyfem-env/bin/activate
 ```
 
 On Windows PowerShell:
 
 ```powershell
-pyfem-env\Scripts\Activate.ps1
+py -m venv pyfem-env
+.\pyfem-env\Scripts\Activate.ps1
 ```
 
-Install PyFEM in editable mode:
+Then install PyFEM in editable mode with the development extra:
 
 ```bash
 python -m pip install --upgrade pip
-pip install -e .
+python -m pip install -e ".[dev]"
 ```
 
 Create a branch for your contribution:
@@ -159,10 +167,11 @@ added, explain in the pull request how the change was verified.
 The canonical local test command is:
 
 ```bash
-python -m pytest test
+uv run --no-sync pytest -q
 ```
 
-The test suite also supports the standard-library unittest runner:
+If using the pip environment, run `python -m pytest test`. The test suite also
+supports the standard-library unittest runner:
 
 ```bash
 python -m unittest discover -s test -p "*.py"