Merge pull request #124 from weeklydevchat/pyproject-uv-lock

Use best-practice pyproject.toml, and uv for managing dependencies

Author: normanlorrain

.dockerignore

@@ -0,0 +1,4 @@
+.venv
+__pycache__
+*.pyc
+.git*

.github/dependabot.yml

@@ -1,6 +1,6 @@
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "weekly"

.github/workflows/ci.yml

@@ -14,19 +14,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: 3.x
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --frozen --no-dev
+
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
       - uses: actions/cache@v5
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install -r requirements.txt 
-      - run: mkdocs gh-deploy --force
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

README.md

@@ -36,16 +36,23 @@ This is a static site built with [MkDocs Material](https://squidfunk.github.io/m
 
 1. Install dependencies:
    ```bash
-   pip install mkdocs-material
+   uv sync
    ```
 
 2. Start the development server:
    ```bash
-   mkdocs serve
+   uv run mkdocs serve       
    ```
 
 3. Open your browser to [http://127.0.0.1:8000](http://127.0.0.1:8000)
 
+
+4. Run the image scripts if required: 
+   ```bash
+   uv run python scripts/optimize_image.py foo.png
+   uv run scripts/optimize_all_images.sh 
+   ```
+
 ### Local Development (Docker)
 
 1. Start the development server:
@@ -125,7 +132,7 @@ These scripts will:
 After adding an image to a post, run the optimization script to convert it to WebP and resize it for the web:
 
 ```bash
-python3 scripts/optimize_image.py docs/posts/YYYY/MM/DD/your_image.png
+uv run python scripts/optimize_image.py docs/posts/YYYY/MM/DD/your_image.png
 ```
 
 This will create an optimized `.webp` file alongside the original. Update your post's markdown to reference the new `.webp` file, then delete the original if no longer needed.
@@ -141,19 +148,16 @@ This will create an optimized `.webp` file alongside the original. Update your p
 
 ```bash
 # Optimize a single image with defaults
-python3 scripts/optimize_image.py docs/posts/2026/04/14/photo.png
+uv run python scripts/optimize_image.py docs/posts/2026/04/14/photo.png
 
 # Batch optimize multiple images
-python3 scripts/optimize_image.py docs/posts/2026/04/14/*.png docs/posts/2026/04/14/*.jpg
+uv run python scripts/optimize_image.py docs/posts/2026/04/14/*.png docs/posts/2026/04/14/*.jpg
 
 # Custom quality and max width
-python3 scripts/optimize_image.py --quality 90 --max-width 1600 image.jpeg
+uv run python scripts/optimize_image.py --quality 90 --max-width 1600 image.jpeg
 ```
 
-> **Note:** This script requires [Pillow](https://pillow.readthedocs.io/). Install dev dependencies with:
-> ```bash
-> pip install -r requirements-dev.txt
-> ```
+
 
 ### Categories and Tags
 
@@ -163,15 +167,15 @@ To see all categories and tags currently in use, run:
 
 **Bash (Linux/macOS)**:
 ```bash
-python3 scripts/find_tags_categories.py
+uv run python scripts/find_tags_categories.py
 ```
 
 **PowerShell (Windows)**:
 ```powershell
-python scripts/find_tags_categories.py
+uv run python scripts/find_tags_categories.py
 ```
 
-This script requires `pyyaml`, which is included in `requirements.txt`. It is also run automatically by the `create_post` scripts when scaffolding a new post.
+This script requires `pyyaml`, which is included in the dev dependencies. It is also run automatically by the `create_post` scripts when scaffolding a new post.
 
 ## Updating Sponsors
 
@@ -182,12 +186,11 @@ Sponsor and donor entries live in [`data/sponsors.yml`](data/sponsors.yml), whic
 ```
 .
 ├── mkdocs.yml                 # Main configuration file
-├── requirements.txt           # Python dependencies
+├── pyproject.toml             # Python dependencies + uv config
+├── uv.lock                    # Locked dependency tree
 ├── docker-compose.yml         # Docker development environment
 ├── create_post.sh             # Bash script to create blog posts
 ├── create_post.ps1            # PowerShell script to create blog posts
-├── requirements-dev.in         # Dev-only dependency pins (e.g. Pillow)
-├── requirements-dev.txt        # Compiled dev dependencies
 ├── scripts/
 │   ├── find_tags_categories.py # List all existing tags and categories
 │   └── optimize_image.py       # Optimize images for the web (PNG/JPEG → WebP)
@@ -225,15 +228,15 @@ mkdocs build                    # Build static site to site/ directory
 mkdocs build --clean            # Clean build
 
 # Optimize an image for the web
-python3 scripts/optimize_image.py docs/posts/YYYY/MM/DD/image.png
+uv run python scripts/optimize_image.py docs/posts/YYYY/MM/DD/image.png
 
 # Help
 mkdocs -h                       # Show help
 
 # Docker
 docker compose up app           # Start development server (with hot reloading)
 docker compose down             # Stop containers
-docker compose down -v          # Stop containers and remove volumes (pip cache)
+docker compose down -v          # Stop containers and remove volumes (uv cache)
 ```
 
 ## Deployment

docker-compose.yml

@@ -1,18 +1,21 @@
 services:
   app:
-    image: python:3.14-slim
-    command: python -m mkdocs serve -a 0.0.0.0:8000 --watch-theme --livereload
-    entrypoint: /app/docker-entrypoint.sh
+    image: ghcr.io/astral-sh/uv:python3.14-trixie-slim
     working_dir: /app
+    entrypoint: /app/docker-entrypoint.sh
+    command: uv run -- mkdocs serve -a 0.0.0.0:8000 --watch-theme --livereload
     ports:
-      - 8000:8000
+      - "8000:8000"
     volumes:
       - .:/app
-      - pip-cache:/root/.cache/pip
+      - uv-cache:/root/.cache/uv
+      # Optional: protect .venv if you ever create one locally
+      - /app/.venv
     environment:
       - PYTHONUNBUFFERED=1
+      - UV_LINK_MODE=copy          # helps with bind mounts
     stdin_open: true
     tty: true
 
 volumes:
-  pip-cache:
+  uv-cache:

docker-entrypoint.sh

@@ -1,6 +1,9 @@
-#!/bin/bash
+#!/bin/sh
 set -e
 
-pip install -r requirements.txt
+uv sync --frozen --no-dev   # or remove --no-dev if you want dev deps
+
+# Optional: make sure mkdocs is in PATH
+export PATH="/app/.venv/bin:$PATH"
 
 exec "$@"

pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "weeklydevchat-github-io"
+version = "0.1.0"
+requires-python = ">=3.14"
+dependencies = [
+    "mkdocs-material>=9.7.0",
+    "pygments~=2.20.0",
+    "urllib3>=2.7.0",
+]
+
+# Dependencies are managed from this `pyproject.toml` with `uv`, not `requirements*.txt`.
+# Install the project environment with `uv sync` and run tools/scripts with `uv run <command>`.
+[dependency-groups]
+dev = [
+    "pillow>=12.2.0",
+    "PyYAML>=6.0.1"
+
+    # Add dev-only tools here when needed; they will be installed by `uv sync`.
+]