feat: Add optional MkDocs documentation setup with Material theme

.github/workflows/docs.yml

@@ -0,0 +1,82 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - 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@v5
+        with:
+          python-version: 3.x
+
+      - name: Install uv
+        run: pip install uv
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Deploy documentation
+        run: uv run mkdocs gh-deploy --force
+
+  build-check:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Check build output
+        run: |
+          echo "✅ Documentation builds successfully"
+          echo "📊 Site size: $(du -sh site/ | cut -f1)"
+          echo "📄 Pages built: $(find site/ -name "*.html" | wc -l)"

.gitignore

@@ -16,3 +16,7 @@ docker/.env
 .ruff_cache/*
 .aider*
 CLAUDE.md
+
+# Documentation build artifacts
+site/
+.cache/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: compile-deps setup clean-pyc clean-test clean-venv clean test mypy lint format check clean-example dev-env refresh-containers rebuild-images build-image push-image
+.PHONY: compile-deps setup clean-pyc clean-test clean-venv clean test mypy lint format check clean-example docs-install docs-build docs-serve docs-check docs-clean dev-env refresh-containers rebuild-images build-image push-image
 
 # Module name - will be updated by init script
 MODULE_NAME := src
@@ -62,6 +62,55 @@ format: setup  # Run ruff formatter
 
 check: setup lint format test mypy  # Run all quality checks
 
+# Documentation
+###############
+DOCS_PORT ?= 8000
+
+docs-install: setup  ## Install documentation dependencies
+	@echo "Installing documentation dependencies..."
+	uv sync --group dev
+	@echo "Documentation dependencies installed"
+
+docs-build: docs-install  ## Build documentation site
+	@echo "Building documentation..."
+	uv run mkdocs build --strict
+	@echo "Documentation built successfully"
+	@echo "📄 Site location: site/"
+	@echo "🌐 Open site/index.html in your browser to view"
+
+docs-serve: docs-install  ## Serve documentation locally with live reload
+	@echo "Starting documentation server with live reload..."
+	@echo "📍 Documentation will be available at:"
+	@echo "   - Local: http://localhost:$(DOCS_PORT)"
+	@echo "🔄 Changes will auto-reload (press Ctrl+C to stop)"
+	@echo ""
+	@echo "💡 To use a different port: make docs-serve DOCS_PORT=9999"
+	uv run mkdocs serve --dev-addr 0.0.0.0:$(DOCS_PORT)
+
+docs-check: docs-build  ## Check documentation build and links
+	@echo "Checking documentation..."
+	@echo "📊 Site size: $$(du -sh site/ | cut -f1)"
+	@echo "📄 Pages built: $$(find site/ -name "*.html" | wc -l)"
+	@echo "🔗 Checking for common issues..."
+	@if grep -r "404" site/ >/dev/null 2>&1; then \
+		echo "⚠️  Found potential 404 errors"; \
+	else \
+		echo "✅ No obvious 404 errors found"; \
+	fi
+	@if find site/ -name "*.html" -size 0 | grep -q .; then \
+		echo "⚠️  Found empty HTML files"; \
+		find site/ -name "*.html" -size 0; \
+	else \
+		echo "✅ No empty HTML files found"; \
+	fi
+	@echo "Documentation check complete"
+
+docs-clean:  ## Clean documentation build files
+	@echo "Cleaning documentation build files..."
+	rm -rf site/
+	rm -rf .cache/
+	@echo "Documentation cleaned"
+
 # Project Management
 ##################
 clean-example:  # Remove example code (use this to start your own project)

docs/getting-started.md

@@ -0,0 +1,143 @@
+# Getting Started with Python Collab Template
+
+This guide walks you through using this template to create a new Python project.
+
+## Prerequisites
+
+- Python 3.9 or higher
+- Git
+- GitHub account (for template usage)
+
+## Creating a Project from This Template
+
+### Step 1: Create Repository from Template
+
+1. Go to this template repository on GitHub
+2. Click **"Use this template"** button
+3. Choose **"Create a new repository"**
+4. Fill in your repository details:
+   - Repository name (e.g., `my-awesome-project`)
+   - Description
+   - Public/Private visibility
+
+### Step 2: Clone and Initialize
+
+1. Clone your new repository:
+   ```bash
+   git clone https://github.com/your-username/your-project-name.git
+   cd your-project-name
+   ```
+
+2. Initialize your project:
+   ```bash
+   make init
+   ```
+
+3. Follow the interactive prompts:
+   - **Project name**: Enter your project name (e.g., "My Awesome Project")
+   - **Description**: Brief description of your project
+   - **Author info**: Your name and email (auto-detected from git config)
+   - **Example code**: Choose how to handle example code:
+     - Keep (useful for reference)
+     - Minimal (basic working example)
+     - Remove (clean slate)
+   - **Documentation**: Set up MkDocs documentation (default: yes)
+   - **Pre-commit hooks**: Enable quality checks on commit (default: yes)
+
+### Step 3: Verify Setup
+
+After initialization, verify everything works:
+
+```bash
+# Run all quality checks
+make check
+
+# If you enabled documentation
+make docs-serve
+```
+
+## Project Structure After Initialization
+
+Your initialized project will have:
+
+```
+your-project-name/
+├── your_project_name/          # Main package (renamed from src/)
+├── tests/                      # Test files
+├── docs/                       # Documentation (if enabled)
+├── .github/workflows/          # CI/CD workflows
+├── pyproject.toml             # Project configuration
+├── Makefile                   # Development commands
+└── README.md                  # Project documentation
+```
+
+## Development Workflow
+
+### Daily Development
+
+1. Make your changes to the code
+2. Add or update tests
+3. Run quality checks:
+   ```bash
+   make check
+   ```
+4. Update documentation if needed
+5. Commit and push
+
+### Available Commands
+
+Your project comes with these make targets:
+
+- `make setup` - Set up development environment
+- `make test` - Run tests with coverage
+- `make lint` - Run linting with auto-fix
+- `make format` - Format code
+- `make mypy` - Run type checking
+- `make check` - Run all quality checks
+- `make docs-serve` - Serve documentation locally (if enabled)
+- `make docs-build` - Build documentation (if enabled)
+- `make docs-check` - Validate documentation build (if enabled)
+
+### Documentation (If Enabled)
+
+If you chose to set up documentation:
+
+1. **Local development**:
+   ```bash
+   make docs-serve
+   # Visit http://localhost:8000
+   ```
+
+2. **Content organization**:
+   - `docs/index.md` - Project homepage
+   - `docs/getting-started.md` - User guide
+   - `docs/reference/api.md` - Auto-generated API docs
+
+3. **GitHub Pages setup**:
+   - Go to repository Settings → Pages
+   - Set source to "GitHub Actions"
+   - Documentation will auto-deploy on main branch pushes
+
+### CI/CD
+
+Your project includes GitHub Actions workflows:
+
+- **Quality checks** (`tests.yml`): Runs on PRs and pushes
+- **Documentation** (`docs.yml`): Deploys docs to GitHub Pages (if enabled)
+
+## Next Steps
+
+1. **Update README.md** with project-specific information
+2. **Add your code** in the main package directory
+3. **Write tests** for your functionality
+4. **Update documentation** to describe your project
+5. **Set up GitHub Pages** (if documentation enabled)
+6. **Configure repository settings** (branch protection, etc.)
+
+## Tips
+
+- The template includes example code you can reference or remove
+- All configuration follows modern Python best practices
+- The documentation system auto-generates API docs from docstrings
+- Pre-commit hooks ensure code quality before commits
+- Use `make` commands for consistent development workflow

docs/index.md

@@ -0,0 +1,67 @@
+# Python Collab Template
+
+A modern, collaborative Python project template with comprehensive tooling and best practices built-in.
+
+## 🎯 Template Features
+
+This template provides everything you need for a professional Python project:
+
+- 🔧 **Modern Tooling**: UV package manager, Ruff formatting/linting, MyPy type checking
+- 🧪 **Testing**: pytest with coverage reporting and CI integration
+- 📚 **Documentation**: Optional MkDocs + Material theme with auto-generation
+- 🚀 **CI/CD**: GitHub Actions with quality checks and automated deployment
+- 🐳 **Development**: Docker support and pre-commit hooks
+- 📦 **Packaging**: Modern pyproject.toml configuration with hatchling
+
+## 🚀 Quick Start
+
+### Using This Template
+
+1. **Create a new repository** from this template on GitHub
+2. **Clone your new repository**:
+   ```bash
+   git clone https://github.com/your-username/your-project-name.git
+   cd your-project-name
+   ```
+3. **Initialize your project**:
+   ```bash
+   make init
+   ```
+4. **Follow the prompts** to customize your project
+
+### What `make init` Does
+
+The initialization script will:
+- Prompt for project name, description, and author information
+- Update all configuration files with your project details
+- Choose how to handle example code (keep, simplify, or remove)
+- Optionally set up MkDocs documentation (default: yes)
+- Rename directories and update imports
+- Set up git repository and pre-commit hooks
+
+## 📁 Template Structure
+
+```
+python-collab-template/
+├── src/                        # Source code (renamed during init)
+├── tests/                      # Test files
+├── scripts/                    # Utility scripts (including init)
+├── templates/                  # Documentation templates
+├── docker/                     # Docker configuration
+├── .github/workflows/          # CI/CD automation
+├── pyproject.toml             # Project configuration
+├── Makefile                   # Development commands
+└── README.md                  # Project documentation
+```
+
+## 🛠️ Available Commands
+
+After initialization, your project will have these commands:
+
+- `make setup` - Set up development environment
+- `make test` - Run tests with coverage
+- `make check` - Run all quality checks
+- `make docs-serve` - Serve documentation locally (if enabled)
+- `make docs-build` - Build documentation (if enabled)
+
+For complete usage instructions, see the [Getting Started](getting-started.md) guide.

docs/reference/api.md

@@ -0,0 +1,9 @@
+# API Reference
+
+This page contains the auto-generated API documentation for the project.
+
+::: src
+    options:
+      show_root_heading: true
+      members_order: source
+      show_source: false