Add VS Code dev container with hatch and Python 3.10-3.14

.devcontainer/README.md

@@ -0,0 +1,135 @@
+# Development Container Configuration
+
+This directory contains the configuration for a VS Code development container that provides a complete development environment for the wizard-template project.
+
+## Features
+
+- **Python Versions**: Includes Python 3.10, 3.11, 3.12, 3.13, and 3.14 (managed via pyenv)
+- **Hatch**: Pre-installed project management tool
+- **Pre-configured VS Code**: Extensions and settings optimized for Python development
+- **Pre-commit Hooks**: Automatically installed on container creation
+
+## What's Included
+
+### Tools
+
+- **Hatch**: Python project management tool (installed via pipx)
+- **Pyenv**: Python version management (for managing multiple Python versions)
+- **Git**: Version control
+- **Build tools**: Essential build dependencies for Python packages
+
+### VS Code Extensions
+
+- Python extension with Pylance
+- Ruff linter and formatter
+- Better TOML support
+- GitHub Copilot (if available)
+
+### Configuration
+
+- Python formatting and linting configured for Ruff
+- Format on save enabled
+- Pytest testing framework configured
+- Virtual environments stored in `.venv` directory
+
+## Usage
+
+### Opening in VS Code
+
+1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+2. Open the project in VS Code
+3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container")
+4. Wait for the container to build and the post-create script to complete
+
+### First-Time Setup
+
+The post-create script automatically:
+1. Installs pyenv for Python version management
+2. Installs Python versions 3.10, 3.11, 3.12, 3.13, and 3.14
+3. Configures hatch to use local virtual environments
+4. Installs pre-commit hooks
+
+### Working with Multiple Python Versions
+
+All Python versions are available via pyenv:
+
+```bash
+# List all installed Python versions
+pyenv versions
+
+# Use a specific version for the current shell
+pyenv shell 3.11
+
+# Use a specific version for the current directory
+pyenv local 3.11
+
+# Run tests with a specific Python version using hatch
+hatch run +py=3.11 test
+```
+
+### Running Common Tasks
+
+```bash
+# Install dependencies and run tests
+hatch run test
+
+# Run quality assurance checks
+hatch run qa
+
+# Build documentation
+hatch run docs:build
+
+# Run pre-commit hooks
+hatch run check
+```
+
+## Customization
+
+To customize the development container:
+
+1. Edit `devcontainer.json` to add features, extensions, or change settings
+2. Modify `post-create.sh` to change post-creation setup steps
+3. Rebuild the container: Command Palette → "Dev Containers: Rebuild Container"
+
+## Troubleshooting
+
+### Python Version Not Found
+
+If a Python version is not available:
+
+```bash
+# List available versions
+pyenv install --list
+
+# Install a specific version
+pyenv install 3.12.1
+
+# Set it as global
+pyenv global 3.10.x 3.11.x 3.12.1 3.13.x 3.14.x
+```
+
+### Hatch Not Found
+
+If hatch is not available:
+
+```bash
+# Install hatch via pipx
+pipx install hatch
+
+# Or install it via pip
+pip install hatch
+```
+
+## Technical Details
+
+- **Base Image**: `mcr.microsoft.com/devcontainers/python:1-3.12-bookworm`
+- **Default Python**: 3.12 (from base image)
+- **Additional Pythons**: Installed via pyenv
+- **Package Manager**: Hatch with uv installer
+- **User**: `vscode` (non-root)
+
+## References
+
+- [Dev Containers Documentation](https://code.visualstudio.com/docs/devcontainers/containers)
+- [Hatch Documentation](https://hatch.pypa.io/)
+- [Pyenv Documentation](https://github.com/pyenv/pyenv)

.devcontainer/devcontainer.json

@@ -0,0 +1,47 @@
+{
+"name": "Wizard Template Python Dev",
+"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bookworm",
+
+"features": {
+"ghcr.io/devcontainers-extra/features/pipx:latest": {
+"package": "hatch",
+"version": "latest"
+},
+"ghcr.io/devcontainers-contrib/features/apt-packages:1": {
+"packages": "software-properties-common,build-essential,libssl-dev,zlib1g-dev,libbz2-dev,libreadline-dev,libsqlite3-dev,curl,git,libncursesw5-dev,xz-utils,tk-dev,libxml2-dev,libxmlsec1-dev,libffi-dev,liblzma-dev"
+}
+},
+
+"customizations": {
+"vscode": {
+"extensions": [
+"ms-python.python",
+"ms-python.vscode-pylance",
+"ms-python.black-formatter",
+"charliermarsh.ruff",
+"tamasfe.even-better-toml",
+"GitHub.copilot",
+"GitHub.copilot-chat"
+],
+"settings": {
+"python.defaultInterpreterPath": "/usr/local/bin/python",
+"python.linting.enabled": true,
+"python.linting.pylintEnabled": false,
+"python.formatting.provider": "none",
+"python.testing.pytestEnabled": true,
+"[python]": {
+"editor.defaultFormatter": "charliermarsh.ruff",
+"editor.formatOnSave": true,
+"editor.codeActionsOnSave": {
+"source.fixAll": "explicit",
+"source.organizeImports": "explicit"
+}
+}
+}
+}
+},
+
+"postCreateCommand": "bash .devcontainer/post-create.sh",
+
+"remoteUser": "vscode"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+set -e
+
+echo "🚀 Starting post-create setup..."
+
+# Install pyenv for managing multiple Python versions
+# Note: pyenv-installer is the official pyenv installation method
+# See: https://github.com/pyenv/pyenv-installer
+echo "📦 Installing pyenv..."
+curl -fsSL https://pyenv.run | bash
+
+# Add pyenv to PATH for this script
+export PYENV_ROOT="$HOME/.pyenv"
+export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+
+# Configure shell for pyenv
+echo '' >> ~/.bashrc
+echo '# Pyenv configuration' >> ~/.bashrc
+echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
+echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
+echo 'eval "$(pyenv init -)"' >> ~/.bashrc
+
+# Install required Python versions
+echo "🐍 Installing Python versions..."
+PYTHON_VERSIONS=("3.10" "3.11" "3.12" "3.13" "3.14")
+
+for version in "${PYTHON_VERSIONS[@]}"; do
+    echo "Installing Python $version..."
+    # Get the latest patch version for each minor version
+    latest_patch=$(pyenv install --list | grep -E "^\s*$version\.[0-9]+$" | tail -1 | tr -d ' ')
+    if [ -n "$latest_patch" ]; then
+        pyenv install -s "$latest_patch"
+        echo "✅ Installed Python $latest_patch"
+    else
+        echo "⚠️  Could not find Python $version"
+    fi
+done
+
+# Set all installed versions as global (available system-wide)
+echo "🔧 Configuring global Python versions..."
+INSTALLED_VERSIONS=$(pyenv versions --bare | tr '\n' ' ')
+pyenv global $INSTALLED_VERSIONS
+
+# Verify Python installations
+echo "✅ Available Python versions:"
+pyenv versions
+
+# Verify hatch is available
+echo "🔍 Verifying hatch installation..."
+if command -v hatch &> /dev/null; then
+    echo "✅ Hatch is installed: $(hatch --version)"
+else
+    echo "⚠️  Hatch not found, installing via pipx..."
+    pipx install hatch
+fi
+
+# Configure hatch to use local virtual environments
+echo "🔧 Configuring hatch..."
+hatch config set dirs.env.virtual .venv
+
+# Install pre-commit hooks
+echo "📋 Installing pre-commit hooks..."
+hatch run pre-commit-install
+
+echo "✨ Post-create setup complete!"
+echo ""
+echo "Available Python versions:"
+pyenv versions
+echo ""
+echo "To use a specific Python version, run:"
+echo "  pyenv shell <version>  # For current shell"
+echo "  pyenv local <version>  # For current directory"
+echo ""
+echo "Hatch will automatically use the appropriate Python version based on the matrix configuration."

.github/copilot-instructions.md

@@ -12,6 +12,7 @@ This is a Python project template that includes:
 - Documentation with Jupyter Book
 - CI/CD workflows with GitHub Actions
 - Project management with Hatch
+- VS Code dev container with multi-version Python support
 
 ## First-Time Setup (CRITICAL)
 
@@ -30,6 +31,24 @@ This script:
 
 **Do not skip this step** - it must be run immediately after cloning a new project from this template.
 
+## Development Environment
+
+### Dev Container (Recommended)
+
+This project includes a VS Code dev container configuration (`.devcontainer/`) that provides:
+
+- **Hatch**: Pre-installed via pipx
+- **Multiple Python versions**: Python 3.10, 3.11, 3.12, 3.13, and 3.14 (managed via pyenv)
+- **Pre-configured VS Code**: Extensions and settings for Python development
+- **Automatic setup**: Post-create script installs all Python versions and pre-commit hooks
+
+To use the dev container:
+1. Open the project in VS Code
+2. Click "Reopen in Container" when prompted
+3. Wait for the container to build and setup to complete
+
+See `.devcontainer/README.md` for detailed information about the dev container configuration.
+
 ## Project Management Tool: Hatch
 
 This project uses [Hatch](https://hatch.pypa.io/) as the primary project management tool.

README.md

@@ -31,6 +31,25 @@ This is a general-purpose template that aims to provide a magical start to any P
 
 Check out the documentation for more details on how to use the template and its features: <https://docs.fschuch.com/wizard-template>.
 
+## Quick Start
+
+### Using Dev Container (Recommended)
+
+The easiest way to get started is using the provided VS Code dev container:
+
+1. Install [Docker](https://docs.docker.com/get-docker/) and [VS Code](https://code.visualstudio.com/)
+2. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+3. Open this project in VS Code
+4. Click "Reopen in Container" when prompted (or use Command Palette: "Dev Containers: Reopen in Container")
+
+The dev container includes:
+- **Hatch**: Pre-installed and configured
+- **Multiple Python versions**: 3.10, 3.11, 3.12, 3.13, and 3.14 (via pyenv)
+- **Pre-configured tools**: All linting, formatting, and testing tools ready to use
+- **VS Code extensions**: Python development extensions pre-installed
+
+See [`.devcontainer/README.md`](.devcontainer/README.md) for more details.
+
 ### For AI Assistants
 
 If you're an AI coding assistant (like GitHub Copilot), please read [`.github/copilot-instructions.md`](.github/copilot-instructions.md) for important context about this template, including:

docs/getting-started/use-this-template.md

@@ -1,5 +1,44 @@
 # How to use this Template
 
+## Option 1: Using Dev Container (Recommended)
+
+The easiest way to get started is using the VS Code dev container:
+
+1. Create your project by clicking on [Use this template](https://github.com/new?template_name=wizard-template&template_owner=fschuch) to generate a new repository from this template.
+
+1. Clone your repository:
+
+   ```bash
+   git clone <your-repo-url>
+   cd <your-repo-name>
+   ```
+
+1. Open the project in VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) installed.
+
+1. Click "Reopen in Container" when prompted (or use Command Palette: "Dev Containers: Reopen in Container").
+
+1. Wait for the container to build and the post-create script to complete. This will:
+   - Install Hatch
+   - Install Python versions 3.10, 3.11, 3.12, 3.13, and 3.14
+   - Install pre-commit hooks
+   - Configure the development environment
+
+1. Run the renaming script to customize your project:
+
+   ```bash
+   hatch run _wizard
+   ```
+
+1. Verify everything is working:
+
+   ```bash
+   hatch run qa
+   ```
+
+See [`.devcontainer/README.md`](https://github.com/fschuch/wizard-template/blob/main/.devcontainer/README.md) for more details about the dev container configuration.
+
+## Option 2: Manual Setup
+
 1. Create your project by clicking on [Use this template](https://github.com/new?template_name=wizard-template&template_owner=fschuch) to generate a new repository from this template. Choose a name for your project, and optionally, a description. Ensure to mark the repository as public or private according to your needs.
 
    ````{note}