📝 docs: add mkdocs

Author: bassemkaroui

.github/workflows/docs.yaml

@@ -0,0 +1,51 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv pip install --system -r docs/requirements.txt
+
+      - name: Build documentation
+        if: github.event_name == 'pull_request'
+        run: mkdocs build --strict
+        env:
+          CI: "true"
+
+      - name: Deploy documentation
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        run: mkdocs gh-deploy --force
+        env:
+          CI: "true"
+          DEPLOY: "true"

README.md

@@ -73,7 +73,7 @@ A modern, batteries‑included [Copier](https://github.com/copier-org/copier) te
     - **Dependency Updates** (optional): Choose between Dependabot or self-hosted Renovate via the `dependency_updater` template variable.
         - **Dependabot** (`dependabot.yml`): Opens weekly PRs to keep GitHub Actions dependencies up to date.
         - **Renovate** (`renovate.yaml` + `renovate.json5`): Self-hosted via GitHub Actions. Updates all dependencies (Python packages, pre-commit hooks, GitHub Actions, lock files) with smart grouping and automerge.
-          Supports PAT or GitHub App authentication via the `renovate_auth_method` variable. See the [Renovate setup guide](docs/renovate-setup.md) for detailed instructions.
+          Supports PAT or GitHub App authentication via the `renovate_auth_method` variable. See the [Renovate setup guide](renovate-setup.md) for detailed instructions.
 
     These workflows are generated into `.github/workflows/` in the scaffolded project. You can customize them further as needed.
 

docs/configuration/variables.md

@@ -0,0 +1,82 @@
+# Template Variables
+
+When running `copier copy`, you'll be prompted for the following variables. They control what gets generated in your project.
+
+## Project Information
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `project_name` | Project name (lowercase, letters/digits/dashes) | Current folder name |
+| `project_description` | Short summary of what your project does | -- |
+| `project_keywords` | Comma-separated keywords for the package | `python,<project_name>` |
+| `author_fullname` | Your full name | From `git config` |
+| `author_email` | Your email address | From `git config` |
+
+## Repository
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `repository_provider` | Where you host your repo (`github` or `other`) | `github` |
+| `author_github_handle` | Your GitHub username | Derived from `author_fullname` |
+| `homepage` | Project homepage URL | `https://<user>.github.io/<project>` |
+| `repository` | Repository URL | `https://github.com/<user>/<project>` |
+| `documentation` | Documentation URL | Same as `homepage` |
+
+## Python
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `python_version` | Default Python version for development | `3.12` |
+| `min_python_version` | Minimum supported Python version | `3.10` |
+
+## Features
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `with_typer_cli` | Include a [Typer](https://typer.tiangolo.com/) CLI scaffold | `false` |
+| `cli_name` | CLI command name (if Typer enabled) | `<project_name>` |
+| `with_strict_typing` | Enable strict typing with `py.typed` marker | `false` |
+| `with_settings` | Include [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) | `true` |
+| `with_doppler` | Add [Doppler](https://www.doppler.com/) secrets integration | `false` |
+| `doppler_project` | Doppler project name (if Doppler enabled) | `<project_name>` |
+
+## Testing
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `tox` | Include Tox configuration for multi-version testing | `true` |
+| `pytest_xdist` | Enable parallel test execution with pytest-xdist | `false` |
+| `coverage_threshold` | Minimum test coverage percentage (0-100) | `100` |
+
+## Commits & Releases
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `with_conventional_commits` | Enforce [Conventional Commits](https://www.conventionalcommits.org/) | `true` |
+| `cz_gitmoji` | Include emojis in commit messages | `true` |
+| `publish_to_pypi` | Publish releases to PyPI | `false` |
+
+## Docker
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `dockerfile` | Generate Dockerfile and Compose files | `true` |
+| `privileged_container` | Run container as root | `false` |
+| `gpus` | Enable GPU support in Docker | `false` |
+
+## Dependencies
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `dependency_updater` | Dependency update tool (`none`, `dependabot`, `renovate`) | `renovate` |
+| `renovate_auth_method` | Renovate auth method (`pat` or `github_app`) | `pat` |
+
+## License
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `copyright_license` | Project license | `MIT License` |
+| `copyright_holder` | Copyright holder name | `<author_fullname>` |
+
+!!! tip
+    See the full variable definitions with validators in [`copier.yaml`](https://github.com/bassemkaroui/python-template-uv/blob/main/copier.yaml).

docs/css/overrides.css

@@ -1,3 +1,42 @@
 html {
 	font-size: 18px;
 }
+
+/* Hero section */
+.hero {
+	text-align: center;
+	padding: 2rem 1rem 3rem;
+}
+
+.hero-content h1 {
+	font-size: 2.4rem;
+	font-weight: 700;
+	margin-bottom: 0.5rem;
+}
+
+.hero-content p:first-of-type {
+	font-size: 1.15rem;
+	color: var(--md-default-fg-color--light);
+	max-width: 40rem;
+	margin: 0 auto 1.5rem;
+}
+
+.hero-icon {
+	color: var(--md-primary-fg-color);
+}
+
+.hero .md-button {
+	margin: 0.3rem;
+}
+
+/* Feature grid cards */
+.grid.cards > ul > li {
+	border: 1px solid var(--md-default-fg-color--lightest);
+	border-radius: 0.4rem;
+	transition: border-color 0.2s, box-shadow 0.2s;
+}
+
+.grid.cards > ul > li:hover {
+	border-color: var(--md-accent-fg-color);
+	box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+}

docs/features/ci-cd.md

@@ -0,0 +1,50 @@
+# CI/CD
+
+The template generates GitHub Actions workflows for continuous integration, testing, and release automation.
+
+## Main Pipeline (`main.yaml`)
+
+The primary CI/CD workflow runs on pushes to `main` and pull requests:
+
+- **Checks** -- Linting (Ruff), type checking (Mypy), documentation build
+- **Tests** -- Runs pytest across supported Python versions using a matrix strategy
+- **Releases** -- Automatically publishes releases when a Git tag is pushed
+- **Docs Deployment** -- Deploys MkDocs documentation to GitHub Pages
+- **Package Publishing** (optional) -- Publishes to PyPI if `publish_to_pypi` is enabled
+
+## PR Thank You (`pr-thank-you.yaml`)
+
+Posts a fun GIPHY comment on new pull requests using [`docker-action-pr-giphy-comment`](https://github.com/bassemkaroui/docker-action-pr-giphy-comment).
+
+**Required secret:** `GIPHY_API_KEY`
+
+To obtain one, sign up at [GIPHY Developers](https://developers.giphy.com/), create an app, and copy the API key.
+
+## Dependency Updates
+
+Choose your preferred dependency update tool via the `dependency_updater` variable:
+
+### Renovate (`dependency_updater: renovate`)
+
+Self-hosted via GitHub Actions. Updates all dependencies with smart grouping and automerge:
+
+- Python packages and lock files
+- Pre-commit hooks
+- GitHub Actions
+- Docker base images
+
+Supports PAT or GitHub App authentication via the `renovate_auth_method` variable. See the [Renovate setup guide](https://github.com/bassemkaroui/python-template-uv/blob/main/renovate-setup.md) for detailed instructions.
+
+### Dependabot (`dependency_updater: dependabot`)
+
+GitHub-native solution. Opens weekly PRs to keep GitHub Actions dependencies up to date.
+
+## Required Secrets
+
+| Secret | Required For | How to Set |
+|--------|-------------|------------|
+| `GIPHY_API_KEY` | PR thank-you comments | `gh secret set GIPHY_API_KEY` |
+| `PYPI_TOKEN` | PyPI publishing (if enabled) | `gh secret set PYPI_TOKEN` |
+| `RENOVATE_TOKEN` | Renovate with PAT auth | `gh secret set RENOVATE_TOKEN` |
+| `RENOVATE_APP_ID` | Renovate with GitHub App auth | `gh secret set RENOVATE_APP_ID` |
+| `RENOVATE_APP_PRIVATE_KEY` | Renovate with GitHub App auth | `gh secret set RENOVATE_APP_PRIVATE_KEY` |

docs/features/docker.md

@@ -0,0 +1,44 @@
+# Docker
+
+When `dockerfile: true` (the default), the template generates Docker configuration for both production and development use.
+
+## Generated Files
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Multi-stage production build |
+| `compose.yaml` | Production service definition |
+| `compose.override.yaml` | Development overrides (hot-reload, exposed ports) |
+
+## Commands
+
+```bash
+# Build Docker images
+make docker-build
+
+# Start services
+make docker-start
+
+# Stop and remove services
+make docker-stop
+```
+
+## GPU Support
+
+Enable GPU support by setting `gpus: true` during generation. This adds NVIDIA GPU configuration to the Docker setup:
+
+- NVIDIA base image for CUDA support
+- GPU device requests in compose files
+- Appropriate runtime configuration
+
+## Container Security
+
+By default, the container runs as a non-root user matching your host UID/GID. Set `privileged_container: true` during generation if root access is required.
+
+## Development Workflow
+
+The `compose.override.yaml` file is loaded automatically by Docker Compose and adds:
+
+- Volume mounts for live code reloading
+- Exposed ports for local development
+- Environment variable overrides

docs/features/documentation.md

@@ -0,0 +1,44 @@
+# Documentation
+
+Generated projects include a fully configured [MkDocs](https://github.com/mkdocs/mkdocs) setup with the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
+
+## What's Included
+
+- **MkDocs Material** theme with dark/light mode, search, and navigation features
+- **mkdocstrings** for auto-generated API documentation from docstrings
+- **Code highlighting** with copy buttons and annotations
+- **Admonitions**, tabbed content, and other Material extensions
+
+## Local Development
+
+```bash
+# Serve docs with live reload (localhost:8080)
+make docs-serve
+
+# Check that docs build without errors
+make docs-check
+```
+
+## Deployment
+
+```bash
+# Deploy to GitHub Pages
+make docs-deploy
+```
+
+The CI/CD pipeline also deploys docs automatically on pushes to `main`.
+
+## Structure
+
+```
+docs/
+  index.md          # Landing page
+  modules.md        # Auto-generated API reference
+  css/
+    overrides.css   # Custom styling
+mkdocs.yml          # MkDocs configuration
+```
+
+## API Documentation
+
+The template uses [mkdocstrings](https://mkdocstrings.github.io/) with the Python handler to generate API docs from your source code docstrings. Simply document your modules and classes with docstrings, and they appear in the docs automatically.

docs/features/optional.md

@@ -0,0 +1,42 @@
+# Optional Features
+
+These features can be toggled during project generation via template variables.
+
+## Typer CLI (`with_typer_cli`)
+
+Scaffolds a [Typer](https://typer.tiangolo.com/) CLI application with:
+
+- Entry point configured in `pyproject.toml`
+- CLI module with a sample command
+- Customizable CLI name via the `cli_name` variable
+
+```bash
+# Install CLI globally after generation
+make setup-cli
+```
+
+## Strict Typing (`with_strict_typing`)
+
+Enables strict type checking and adds a `py.typed` marker file for [PEP 561](https://peps.python.org/pep-0561/) compliance. This signals to downstream consumers that your package ships inline type information.
+
+## Pydantic Settings (`with_settings`)
+
+Adds [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for typed configuration management. Settings are loaded from environment variables with type validation and can be nested.
+
+Enabled by default (`with_settings: true`).
+
+## Doppler Integration (`with_doppler`)
+
+Adds [Doppler](https://www.doppler.com/) integration for secure secret management. Doppler injects environment variables at runtime, which Pydantic Settings then validates and parses.
+
+Requires `with_settings: true` and a Doppler project name (`doppler_project`).
+
+## Parallel Testing (`pytest_xdist`)
+
+Adds [pytest-xdist](https://github.com/pytest-dev/pytest-xdist) for parallel test execution, which can significantly speed up large test suites.
+
+## Conventional Commits (`with_conventional_commits`)
+
+Enforces the [Conventional Commits](https://www.conventionalcommits.org/) standard using [Commitizen](https://github.com/commitizen-tools/commitizen). Optionally includes [gitmoji](https://github.com/ljnsn/cz-conventional-gitmoji) for emoji-enhanced commit messages (`cz_gitmoji`).
+
+Enables automated changelog generation and semantic version bumping via `make release`.

docs/features/overview.md

@@ -0,0 +1,24 @@
+# Features Overview
+
+python-template-uv generates a fully configured Python project with modern tooling. Here's what you get out of the box:
+
+## Project Management
+
+- **[Task Runner](task-runner.md)** -- All project tasks defined in `mise.toml` with a `Makefile` wrapper for convenience
+- **[uv](https://docs.astral.sh/uv/)** -- Fast Python package and project manager for dependency resolution and virtual environments
+
+## Code Quality
+
+- **[Quality Tools](quality-tools.md)** -- Ruff for formatting and linting, Mypy for type checking, pre-commit hooks for automated checks
+- **[Testing](testing.md)** -- pytest with coverage, optional parallel execution, and multi-version testing with Tox
+
+## Infrastructure
+
+- **[Documentation](documentation.md)** -- MkDocs with Material theme, auto-generated API docs, GitHub Pages deployment
+- **[Docker](docker.md)** -- Production Dockerfile, compose files, development overrides, optional GPU support
+- **[CI/CD](ci-cd.md)** -- GitHub Actions workflows for testing, releasing, docs, and dependency updates
+
+## Customization
+
+- **[Optional Features](optional.md)** -- Typer CLI, strict typing, Pydantic Settings, Doppler integration
+- **[Template Variables](../configuration/variables.md)** -- Full control over what gets generated