From 54e0953482fb1ef819939c2f39a59ed00a7b30fb Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:33:35 -0500
Subject: [PATCH 1/7] docs: add comprehensive template documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create complete documentation suite based on README content:

- overview.md: Template overview and value proposition
- quickstart.md: Step-by-step getting started guide
- template-guide.md: Detailed feature documentation covering:
  * Project structure and components
  * Development tools and workflows
  * GitHub Actions integration
  * Configuration options
  * Trusted publishing setup
- customization.md: Post-creation modification guide covering:
  * Essential customizations
  * Advanced features
  * Project-specific modifications
  * Deployment and maintenance
- index.md: Main documentation hub with navigation
- README.md: Documentation structure and build instructions

All documentation follows 90-column line limits and provides
comprehensive coverage of template features and usage.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/README.md         |  82 +++++++
 docs/customization.md  | 494 +++++++++++++++++++++++++++++++++++++++++
 docs/index.md          |  85 +++++++
 docs/overview.md       | 122 ++++++++++
 docs/quickstart.md     | 227 +++++++++++++++++++
 docs/template-guide.md | 349 +++++++++++++++++++++++++++++
 6 files changed, 1359 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/customization.md
 create mode 100644 docs/index.md
 create mode 100644 docs/overview.md
 create mode 100644 docs/quickstart.md
 create mode 100644 docs/template-guide.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..582f141
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,82 @@
+# Documentation
+
+This directory contains comprehensive documentation for the Python Package Cookiecutter Template.
+
+## Documentation Structure
+
+- **[index.md](index.md)** - Main documentation hub with navigation
+- **[overview.md](overview.md)** - Template overview and value proposition
+- **[quickstart.md](quickstart.md)** - Get started in minutes
+- **[template-guide.md](template-guide.md)** - Detailed feature documentation
+- **[customization.md](customization.md)** - How to modify generated projects
+
+## Building Documentation
+
+This documentation is written in Markdown and can be used with various documentation generators:
+
+### With MkDocs
+```bash
+# Install MkDocs
+pip install mkdocs mkdocs-material
+
+# Create mkdocs.yml (see example below)
+# Serve locally
+mkdocs serve
+
+# Build for deployment
+mkdocs build
+```
+
+### With Sphinx
+```bash
+# Install Sphinx
+pip install sphinx sphinx-rtd-theme myst-parser
+
+# Configure Sphinx to use Markdown
+# Build documentation
+sphinx-build -b html docs/ docs/_build/
+```
+
+### Example mkdocs.yml
+```yaml
+site_name: Python Package Cookiecutter Template
+docs_dir: docs
+site_dir: site
+
+nav:
+  - Home: index.md
+  - Overview: overview.md
+  - Quick Start: quickstart.md
+  - Template Guide: template-guide.md
+  - Customization: customization.md
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - toc:
+      permalink: true
+```
+
+## Contributing to Documentation
+
+When contributing to the documentation:
+
+1. **Keep lines under 90 characters** for readability
+2. **Use clear headings** with consistent hierarchy
+3. **Include code examples** where helpful
+4. **Link between documents** to improve navigation
+5. **Test documentation builds** before submitting
+
+## Viewing Documentation
+
+The documentation can be viewed:
+- **Locally**: Using MkDocs serve or Sphinx build
+- **GitHub**: Markdown files render directly in the repository
+- **GitHub Pages**: When deployed with MkDocs or Sphinx
\ No newline at end of file
diff --git a/docs/customization.md b/docs/customization.md
new file mode 100644
index 0000000..8375287
--- /dev/null
+++ b/docs/customization.md
@@ -0,0 +1,494 @@
+# Customization Guide
+
+After creating your project with the cookiecutter template, you'll want to customize it 
+to match your specific needs. This guide covers the most common modifications and 
+customizations you should consider.
+
+## Essential Customizations
+
+### 1. Project Documentation
+
+#### README.md
+Your generated `README.md` contains template placeholders. Update these sections:
+
+```markdown
+# Your Package Name
+
+**Update this description** to explain what your package does and why someone would use it.
+
+## Installation
+
+```bash
+pip install your-package-name
+```
+
+## Usage
+
+```python
+import your_package
+
+# Add real usage examples here
+```
+
+## Features
+
+- List your actual features
+- Remove template examples
+- Add screenshots or demos if applicable
+```
+
+#### CONTRIBUTING.md
+Update the contribution guidelines to reflect your project's needs:
+
+- **Development setup**: Specific to your project
+- **Code style**: Any additional style requirements
+- **Testing requirements**: Coverage thresholds, test types
+- **Review process**: How you handle pull requests
+
+### 2. Package Configuration
+
+#### pyproject.toml Updates
+
+**Project Metadata**:
+```toml
+[project]
+name = "your-package-name"
+description = "Update with your actual description"
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+keywords = ["add", "relevant", "keywords"]
+classifiers = [
+    # Update these PyPI classifiers
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12", 
+    "Programming Language :: Python :: 3.13",
+]
+```
+
+**Dependencies**:
+```toml
+dependencies = [
+    # Add your actual runtime dependencies
+    "requests>=2.28.0",
+    "pydantic>=2.0.0",
+    # Remove template dependencies you don't need
+]
+
+[dependency-groups]
+dev = [
+    # Add development dependencies specific to your project
+    "pytest-asyncio",  # If you use async code
+    "httpx",          # For HTTP testing
+    # Keep the quality tools unless you prefer alternatives
+]
+```
+
+#### Testing Configuration
+```toml
+[tool.pytest.ini_options]
+# Add markers specific to your project
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+
+# Add test paths specific to your project
+testpaths = ["tests"]
+# Configure coverage
+addopts = "--cov=src/your_package --cov-report=html --cov-report=term-missing"
+```
+
+### 3. Code Quality Configuration
+
+#### Ruff Configuration
+Customize linting rules in `pyproject.toml`:
+
+```toml
+[tool.ruff]
+# Adjust line length if needed
+line-length = 88
+
+[tool.ruff.lint]
+# Add or remove rule categories
+select = ["ALL"]
+ignore = [
+    # Add rules you want to ignore
+    "D203",    # 1 blank line required before class docstring
+    "D213",    # Multi-line docstring summary should start at the second line
+    # Add project-specific ignores
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Different rules for different file types
+"tests/*" = ["S101", "PLR2004"]  # Allow assert and magic values in tests
+"scripts/*" = ["T201"]           # Allow print in scripts
+```
+
+#### Type Checking with ty
+Configure ty for your project needs:
+
+```toml
+[tool.ty]
+# Add specific configuration for ty if needed
+```
+
+### 4. GitHub Workflows Customization
+
+#### Modify Python Version Matrix
+Edit your project's `pyproject.toml`:
+
+```toml
+[tool.your_package.ci]
+test-python-versions = ["3.11", "3.12", "3.13"]  # Adjust as needed
+```
+
+#### Operating System Matrix
+Modify `.github/workflows/release.yaml` if you need different OS coverage:
+
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]  # Adjust as needed
+```
+
+#### Environment Variables
+Add project-specific environment variables to workflows:
+
+```yaml
+env:
+  YOUR_API_KEY: ${{ secrets.YOUR_API_KEY }}
+  DATABASE_URL: ${{ secrets.DATABASE_URL }}
+```
+
+### 5. Documentation Customization
+
+#### MkDocs Configuration
+Edit `mkdocs.yml` to customize your documentation:
+
+```yaml
+site_name: Your Package Documentation
+site_description: Detailed description of your package
+
+# Add custom navigation
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quickstart.md
+    - Configuration: getting-started/configuration.md
+  - User Guide:
+    - CLI Usage: user-guide/cli.md
+    - API Reference: user-guide/api.md
+    - Examples: user-guide/examples.md
+  - Contributing: contributing.md
+  - Changelog: changelog.md
+
+# Customize theme
+theme:
+  name: material  # or your chosen theme
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+```
+
+#### Add Custom Documentation Pages
+Create documentation specific to your project:
+
+```markdown
+# docs/user-guide/api.md
+# API Reference
+
+## Core Functions
+
+### your_function()
+Description of your main function...
+
+## Classes
+
+### YourClass
+Description of your main class...
+```
+
+## Advanced Customizations
+
+### 1. Custom CLI Commands
+
+Extend the CLI in `src/your_package/__main__.py`:
+
+```python
+import typer
+from your_package.commands import data_command, export_command
+
+app = typer.Typer(
+    name="your_package",
+    help="Your package description and main help text.",
+)
+
+# Add your custom commands
+app.add_typer(data_command.app, name="data", help="Data management commands")
+app.add_typer(export_command.app, name="export", help="Export commands")
+
+@app.command()
+def process(
+    input_file: Path = typer.Argument(..., help="Input file to process"),
+    output_file: Path = typer.Option(None, help="Output file path"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
+):
+    """Process an input file and generate output."""
+    # Your command implementation
+    pass
+```
+
+### 2. Configuration Management
+
+Extend settings in `src/your_package/settings.py`:
+
+```python
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+class Settings(BaseSettings):
+    # Database settings
+    database_url: str = "sqlite:///app.db"
+    database_echo: bool = False
+    
+    # API settings
+    api_key: Optional[str] = None
+    api_timeout: int = 30
+    
+    # Logging settings
+    log_level: str = "INFO"
+    log_file: Optional[str] = None
+    
+    # Feature flags
+    enable_feature_x: bool = False
+    
+    class Config:
+        env_prefix = "YOUR_PACKAGE_"
+        env_file = ".env"
+```
+
+### 3. Custom Poe Tasks
+
+Add project-specific tasks to `pyproject.toml`:
+
+```toml
+[tool.poe.tasks]
+# Data management tasks
+migrate = "alembic upgrade head"
+seed-data = "python scripts/seed_database.py"
+backup = "python scripts/backup.py"
+
+# Custom quality tasks
+lint-docs = "ruff check docs/"
+check-security = "bandit -r src/"
+validate-schema = "python scripts/validate_schema.py"
+
+# Deployment tasks
+deploy-staging = "python scripts/deploy.py --env staging"
+deploy-prod = "python scripts/deploy.py --env production"
+
+# Custom sequences
+full-check.sequence = ["ruff", "ty", "test", "check-security"]
+deploy-pipeline.sequence = ["full-check", "build", "deploy-staging"]
+```
+
+### 4. Testing Strategy
+
+#### Custom Test Configuration
+Add test utilities in `tests/conftest.py`:
+
+```python
+import pytest
+from your_package import create_app
+from your_package.database import get_db
+
+@pytest.fixture
+def app():
+    """Create application for testing."""
+    return create_app(testing=True)
+
+@pytest.fixture
+def db():
+    """Create database for testing."""
+    # Setup test database
+    yield get_db()
+    # Cleanup
+
+@pytest.fixture
+def sample_data():
+    """Provide sample data for tests."""
+    return {
+        "users": [...],
+        "products": [...],
+    }
+```
+
+#### Test Categories
+Organize tests with markers:
+
+```python
+# tests/test_integration.py
+import pytest
+
+@pytest.mark.integration
+def test_database_connection():
+    """Test database connectivity."""
+    pass
+
+@pytest.mark.slow
+def test_large_data_processing():
+    """Test processing large datasets."""
+    pass
+```
+
+Run specific test categories:
+```console
+poe test -m "not slow"        # Skip slow tests
+poe test -m integration       # Only integration tests
+poe test -m "unit and not slow"  # Unit tests that are fast
+```
+
+## Project-Specific Modifications
+
+### 1. Remove Unused Features
+
+If you don't need certain template features:
+
+#### Remove Pydantic Settings
+1. Delete `src/your_package/settings.py`
+2. Remove pydantic-settings from dependencies
+3. Update `__main__.py` to remove settings imports
+
+#### Remove File Logging
+1. Remove file logging configuration from `__main__.py`
+2. Update loguru configuration to console-only
+
+#### Simplify CLI
+If you only need a simple CLI:
+1. Remove complex command structure
+2. Simplify `__main__.py` to basic argument parsing
+3. Remove unnecessary CLI dependencies
+
+### 2. Add Domain-Specific Features
+
+#### Web API with FastAPI
+Add FastAPI for web APIs:
+
+```python
+# src/your_package/api.py
+from fastapi import FastAPI
+from your_package.routes import items_router
+
+app = FastAPI(title="Your Package API")
+app.include_router(items_router, prefix="/api/v1")
+```
+
+#### Database Integration
+Add database support:
+
+```python
+# src/your_package/database.py
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+engine = create_engine(settings.database_url)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+```
+
+#### Background Tasks
+Add task queue integration:
+
+```python
+# src/your_package/tasks.py
+from celery import Celery
+
+celery_app = Celery("your_package")
+
+@celery_app.task
+def process_data(data_id: str):
+    """Process data in background."""
+    pass
+```
+
+## Deployment Customizations
+
+### 1. Docker Support
+Add Docker configuration:
+
+```dockerfile
+# Dockerfile
+FROM python:3.13-slim
+
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN pip install uv && uv sync --frozen
+
+COPY src/ ./src/
+RUN uv pip install -e .
+
+CMD ["your-package"]
+```
+
+### 2. Environment Configuration
+Add environment-specific configuration:
+
+```python
+# src/your_package/config.py
+import os
+from enum import Enum
+
+class Environment(str, Enum):
+    DEVELOPMENT = "development"
+    STAGING = "staging"  
+    PRODUCTION = "production"
+
+def get_settings():
+    env = os.getenv("ENVIRONMENT", Environment.DEVELOPMENT)
+    
+    if env == Environment.PRODUCTION:
+        return ProductionSettings()
+    elif env == Environment.STAGING:
+        return StagingSettings()
+    else:
+        return DevelopmentSettings()
+```
+
+### 3. CI/CD Enhancements
+Add deployment steps to `.github/workflows/release.yaml`:
+
+```yaml
+deploy:
+  needs: [publish, github-release]
+  if: success()
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - name: Deploy to production
+      run: |
+        # Your deployment commands
+        echo "Deploying to production..."
+```
+
+## Maintenance Tasks
+
+### Regular Updates
+1. **Dependencies**: Review and update dependencies quarterly
+2. **Python versions**: Add new Python versions as they're released
+3. **GitHub Actions**: Update action versions annually
+4. **Documentation**: Keep documentation current with code changes
+
+### Quality Monitoring
+1. **Test coverage**: Maintain >90% test coverage
+2. **Security**: Run security scans regularly
+3. **Performance**: Monitor package size and import time
+4. **Dependencies**: Monitor for security vulnerabilities
+
+This customization guide should help you adapt the template to your specific needs while maintaining the quality and automation features that make it valuable.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..2cb5489
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,85 @@
+# Python Package Cookiecutter Template Documentation
+
+Welcome to the comprehensive documentation for the Python Package Cookiecutter Template.
+
+## Getting Started
+
+### New to the Template?
+- **[Overview](overview.md)** - Learn what this template offers and why you should use it
+- **[Quick Start](quickstart.md)** - Get your first package running in minutes
+
+### Ready to Dive Deeper?
+- **[Template User Guide](template-guide.md)** - Detailed documentation of all features
+- **[Customization Guide](customization.md)** - How to modify your generated project
+
+## What This Template Provides
+
+### Zero Configuration CI/CD
+- Complete GitHub Actions workflows for testing, building, and publishing
+- Automated PyPI publishing with trusted publishing (no API tokens needed)
+- Documentation auto-deployed to GitHub Pages
+- Quality tools pre-configured: ruff, ty, pytest, coverage reporting
+
+### Modern Python Ecosystem
+- **[uv](https://docs.astral.sh/uv/)** for lightning-fast dependency management
+- **[Typer](https://typer.tiangolo.com)** CLI framework with rich help
+- **[Loguru](https://loguru.readthedocs.io/en/stable/)** for beautiful logging
+- **[Pydantic Settings](https://docs.pydantic.dev/latest/api/pydantic_settings/)** for configuration
+- **[MkDocs](https://www.mkdocs.org/)** with multiple theme options
+
+### Professional Package Structure
+- **src/ layout** following Python packaging best practices
+- **Comprehensive testing** setup with pytest and coverage
+- **Multiple build backends** (uv or hatch)
+- **Semantic versioning** with automated changelog generation
+- **Cross-platform testing** (Linux, macOS, Windows)
+
+## Quick Navigation
+
+| I want to... | Go to... |
+|---------------|-----------|
+| **Understand what this template offers** | [Overview](overview.md) |
+| **Create my first package quickly** | [Quick Start](quickstart.md) |
+| **Learn about all features in detail** | [Template User Guide](template-guide.md) |
+| **Customize my generated project** | [Customization Guide](customization.md) |
+| **See examples and best practices** | [Template User Guide - Examples](template-guide.md#configuration-options) |
+| **Understand the GitHub workflows** | [Template User Guide - GitHub Actions](template-guide.md#github-actions-workflow-details) |
+| **Set up PyPI publishing** | [Template User Guide - Trusted Publishing](template-guide.md#trusted-publishing-setup) |
+
+## Template Workflow
+
+The template enables a seamless development workflow:
+
+1. **Write Code** - Edit your package source files
+2. **Quality Control** - Run `poe qc` to check code quality
+3. **Release** - Run `poe publish` to version and tag
+4. **Live on PyPI** - Automatic publishing via GitHub Actions
+
+## Example Generated Project Structure
+
+```
+your-package/
+├── .github/workflows/     # Complete CI/CD pipeline
+├── docs/                  # MkDocs documentation
+├── src/your_package/      # Your source code
+│   ├── __main__.py        # CLI entry point
+│   └── settings.py        # Configuration (optional)
+├── tests/                 # Comprehensive test suite
+├── pyproject.toml         # Project configuration
+├── README.md              # Project documentation
+└── LICENSE                # Your chosen license
+```
+
+## Support and Contributing
+
+- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/JnyJny/python-package-cookiecutter/issues)
+- **Discussions**: Ask questions on [GitHub Discussions](https://github.com/JnyJny/python-package-cookiecutter/discussions)
+- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines
+
+## License
+
+This template is released under the MIT License. Generated projects use the license you choose during template creation.
+
+---
+
+**Ready to get started?** Head to the [Quick Start Guide](quickstart.md) to create your first package in minutes!
\ No newline at end of file
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100644
index 0000000..4e6b36d
--- /dev/null
+++ b/docs/overview.md
@@ -0,0 +1,122 @@
+# Python Package Cookiecutter Template - Overview
+
+## What is this template?
+
+There are many [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/index.html) 
+[templates](https://www.cookiecutter.io/templates), but this one is mine and I'm sharing 
+it with you. With it, you can quickly create a full-featured Python package designed to 
+be managed with [uv](https://docs.astral.sh/uv/) and 
+[direnv](https://direnv.net), a default [typer](https://typer.tiangolo.com) 
+command-line interface, optional settings using 
+[pydantic-settings](https://docs.pydantic.dev/latest/api/pydantic_settings/) and 
+logging using my favorite logger, [loguru](https://loguru.readthedocs.io/en/stable/). 
+Development activities like testing, code quality checks, and publishing to PyPI are 
+all baked in and ready to go thanks to [Poe The Poet](https://poethepoet.natn.io). 
+Project documentation is automatically configured to deploy to GitHub Pages using 
+[MkDocs](https://www.mkdocs.org/). Best of all, I've added all sorts of templates and 
+base files to help provide a great GitHub experience for you and people that interact 
+with your project repository.
+
+## Why Use This Template?
+
+### Zero Configuration Required
+- **Complete CI/CD pipeline** with GitHub Actions for testing, building, and publishing
+- **Automated PyPI publishing** with trusted publishing (no API tokens needed)
+- **Documentation** auto-deployed to GitHub Pages
+- **Quality tools pre-configured**: ruff, ty, pytest, coverage reporting
+
+### Python Ecosystem
+- **[uv](https://docs.astral.sh/uv/)** for lightning-fast dependency management and 
+  Python version control
+- **[Typer](https://typer.tiangolo.com)** CLI framework with rich help and autocompletion
+- **[Loguru](https://loguru.readthedocs.io/en/stable/)** for beautiful, structured logging
+- **[Pydantic Settings](https://docs.pydantic.dev/latest/api/pydantic_settings/)** for 
+  configuration management
+- **[MkDocs](https://www.mkdocs.org/)** with multiple theme options for documentation
+
+### Package Structure
+- **src/ layout** following Python packaging best practices
+- **Comprehensive testing** setup with pytest and coverage
+- **Multiple build backends** (uv or hatch) 
+- **Semantic versioning** with automated changelog generation
+- **Cross-platform testing** (Linux, macOS, Windows)
+
+### Seamless Workflow
+- **Write Code** - Edit your package source files
+- **Quality Control** - Run `poe qc` to check code quality
+- **Release** - Run `poe publish` to version and tag
+- **Live on PyPI** - Automatic publishing via GitHub Actions
+
+## What You Get
+
+When you create a project with this template, you get:
+
+### Project Structure
+```
+your-package/
+├── .github/              # GitHub workflows and templates
+│   ├── workflows/
+│   │   ├── release.yaml  # Complete CI/CD pipeline
+│   │   └── docs.yml      # Documentation deployment
+│   └── ISSUE_TEMPLATE/   # Issue and PR templates
+├── docs/                 # MkDocs documentation
+├── src/your_package/     # Your package source code
+│   ├── __init__.py
+│   ├── __main__.py       # CLI entry point
+│   ├── self_subcommand.py
+│   └── settings.py       # Optional configuration
+├── tests/                # Test suite
+├── pyproject.toml        # Project configuration
+├── README.md             # Project documentation
+└── LICENSE               # Your chosen license
+```
+
+### Built-in Tools
+- **Testing**: pytest with coverage reporting
+- **Code Quality**: ruff for linting and formatting, ty for type checking
+- **Documentation**: MkDocs with auto-generated API docs
+- **Task Runner**: Poe The Poet for common development tasks
+- **Dependency Management**: uv for fast, reliable dependency resolution
+- **Version Control**: Git with automatic initial commit
+- **CI/CD**: Complete GitHub Actions workflows
+
+### GitHub Integration
+- **Issue Templates**: Bug reports, feature requests, and questions
+- **Pull Request Template**: Contribution guidelines
+- **Dependabot**: Automatic dependency updates
+- **Release Automation**: Semantic versioning with auto-generated changelogs
+- **Documentation Deployment**: Automatic GitHub Pages deployment
+
+## Template Configuration
+
+The template is highly configurable through cookiecutter prompts:
+
+### Required Configuration
+- **Package Name**: Your Python package name
+- **Project Description**: Brief description of your project
+- **Author Information**: Your name and email
+- **License**: Choose from multiple open source licenses
+
+### Optional Features
+- **Pydantic Settings**: Configuration management with environment variables
+- **File Logging**: Optional file-based logging in addition to console
+- **GitHub Repository**: Automatic repository creation and push
+- **Build Backend**: Choose between uv or hatch
+- **Documentation Theme**: Multiple MkDocs theme options
+
+### CI/CD Configuration
+- **Python Version Matrix**: Which Python versions to test against
+- **OS Matrix**: Which operating systems to test on
+- **Testing Strategy**: Comprehensive test matrix or minimal testing
+
+## Next Steps
+
+- [Quick Start Guide](quickstart.md) - Get started in minutes
+- [Template User Guide](template-guide.md) - Detailed feature documentation
+- [Customization Guide](customization.md) - How to modify your generated project
+
+## Support
+
+- **GitHub Issues**: Report bugs or request features
+- **Discussions**: Ask questions and share ideas
+- **Contributing**: See CONTRIBUTING.md for contribution guidelines
\ No newline at end of file
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..fc65e1c
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,227 @@
+# Quick Start Guide
+
+Get your Python package up and running in minutes with this cookiecutter template.
+
+## Prerequisites
+
+### Required Tools
+
+| Tool | Required | Purpose |
+|------|----------|---------|
+| [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/index.html) | ✅ | Creates projects from templates |
+| [git](https://git-scm.com/downloads) | ✅ | Version control system |
+| [uv](https://docs.astral.sh/uv/) | ✅ | Python and dependency management |
+
+### Optional Tools
+
+| Tool | Purpose |
+|------|---------|
+| [direnv](https://direnv.net) | Automatic virtual environment activation |
+| [gh](https://github.com/cli/cli) | GitHub CLI for repository creation |
+
+### Accounts (Optional but Recommended)
+- **GitHub account** for repository hosting and CI/CD
+- **PyPI account** for package publishing
+
+## Step 1: Create Your Project
+
+### Using uvx (Recommended)
+```console
+uvx cookiecutter gh:JnyJny/python-package-cookiecutter
+```
+
+### Using pip
+```console
+pip install cookiecutter
+cookiecutter gh:JnyJny/python-package-cookiecutter
+```
+
+### Configuration Prompts
+
+The template will ask you several questions to configure your project:
+
+#### Basic Information
+```
+package_name [my_package]: your_package_name
+package_description [A short description]: Your package description
+author_name [Your Name]: Your Name
+author_email [your.email@example.com]: your.email@example.com
+github_username [yourusername]: yourusername
+```
+
+#### License Selection
+```
+license [MIT]:
+  1 - MIT
+  2 - Apache-2.0
+  3 - GPL-3.0
+  4 - BSD-3-Clause
+  5 - no-license
+```
+
+#### Feature Options
+```
+use_pydantic_settings [True]: True/False
+log_to_file [False]: True/False
+create_github_repo [False]: True/False
+build_backend [uv]: uv/hatch
+```
+
+#### Testing Configuration
+```
+python_testing_matrix [["3.11", "3.12", "3.13"]]: Python versions to test
+os_testing_matrix [ubuntu-latest]: Operating systems to test
+```
+
+## Step 2: Navigate to Your Project
+
+```console
+cd your_package_name
+```
+
+Your project is now created with:
+- ✅ Virtual environment created and activated
+- ✅ Dependencies installed
+- ✅ Git repository initialized
+- ✅ Initial commit made
+- ✅ (Optional) GitHub repository created
+
+## Step 3: Explore Your Project
+
+### View Available Tasks
+```console
+poe --help
+```
+
+You'll see tasks for:
+- **Testing**: `poe test`, `poe coverage`
+- **Code Quality**: `poe ty`, `poe ruff`, `poe check`, `poe qc`
+- **Publishing**: `poe publish_patch`, `poe publish_minor`, `poe publish_major`
+- **Documentation**: `poe docs-serve`, `poe docs-build`, `poe docs-deploy`
+- **Utilities**: `poe clean`, `poe tree`
+
+### Run Your CLI
+```console
+# Via python module
+python -m your_package_name --help
+
+# Or if installed in development mode
+your_package_name --help
+```
+
+### Run Quality Checks
+```console
+poe qc
+```
+
+This runs:
+- Type checking with `ty`
+- Linting and formatting with `ruff`
+- Tests with `pytest`
+- Coverage reporting
+
+## Step 4: Start Developing
+
+### Edit Your Code
+Your main code lives in:
+- `src/your_package_name/__main__.py` - CLI entry point
+- `src/your_package_name/__init__.py` - Package initialization
+- `src/your_package_name/self_subcommand.py` - Built-in commands
+- `src/your_package_name/settings.py` - Configuration (if enabled)
+
+### Add Tests
+Write tests in the `tests/` directory:
+- `tests/test_cli.py` - CLI testing examples provided
+
+### Update Documentation
+- Edit `README.md` for your project description
+- Add documentation in `docs/` directory
+- Documentation auto-deploys to GitHub Pages
+
+## Step 5: Publish Your Package
+
+### Test Publishing (Optional)
+```console
+# Build your package
+uv build
+
+# Check the built package
+ls dist/
+```
+
+### Publish to PyPI
+```console
+# For bug fixes
+poe publish_patch
+
+# For new features  
+poe publish_minor
+
+# For breaking changes
+poe publish_major
+```
+
+This will:
+1. ✅ Run all quality checks
+2. ✅ Version your package
+3. ✅ Create a git tag
+4. ✅ Trigger GitHub Actions
+5. ✅ Build and publish to PyPI
+6. ✅ Create GitHub release
+7. ✅ Deploy documentation
+
+## Common Development Workflow
+
+```console
+# Make changes to your code
+vim src/your_package_name/__main__.py
+
+# Run quality checks
+poe qc
+
+# Run tests
+poe test
+
+# Commit your changes
+git add .
+git commit -m "Add new feature"
+
+# When ready to release
+poe publish_patch
+```
+
+## Next Steps
+
+- **[Template User Guide](template-guide.md)** - Detailed feature documentation
+- **[Customization Guide](customization.md)** - Modify your project
+- **[GitHub Workflows](workflows.md)** - Understanding the CI/CD pipeline
+
+## Troubleshooting
+
+### Common Issues
+
+**Virtual environment not activated?**
+```console
+source .venv/bin/activate  # Manual activation
+# OR install direnv for automatic activation
+```
+
+**Tests failing?**
+```console
+poe test -v  # Verbose test output
+```
+
+**Build failing?**
+```console
+uv build --verbose  # Detailed build output
+```
+
+**GitHub Actions failing?**
+- Check the Actions tab in your GitHub repository
+- Ensure PyPI trusted publishing is configured (see template-guide.md)
+
+### Getting Help
+
+- **GitHub Issues**: Report bugs or ask questions
+- **Documentation**: Check the complete template guide
+- **Community**: Join discussions on GitHub
\ No newline at end of file
diff --git a/docs/template-guide.md b/docs/template-guide.md
new file mode 100644
index 0000000..2ababa9
--- /dev/null
+++ b/docs/template-guide.md
@@ -0,0 +1,349 @@
+# Template User Guide
+
+This guide provides detailed information about all features available in the Python Package Cookiecutter Template and how to use them effectively.
+
+## Template Features
+
+### Project Structure
+
+The template creates a well-organized project following Python packaging best practices:
+
+```
+your-package/
+├── .cookiecutter.json      # Template configuration used
+├── .envrc                  # direnv configuration (optional)
+├── .github/                # GitHub workflows and templates
+│   ├── workflows/
+│   │   ├── release.yaml    # CI/CD pipeline
+│   │   └── docs.yml        # Documentation deployment
+│   ├── ISSUE_TEMPLATE/     # GitHub issue templates
+│   │   ├── 1_bug_report.yaml
+│   │   ├── 2_feature_request.yaml
+│   │   ├── 3_question.yaml
+│   │   └── config.yaml
+│   ├── PULL_REQUEST_TEMPLATE.md
+│   └── dependabot.yaml     # Dependency updates
+├── .gitignore              # Comprehensive gitignore
+├── CONTRIBUTING.md         # Contribution guidelines
+├── docs/                   # MkDocs documentation
+│   ├── index.md
+│   ├── getting-started/
+│   ├── user-guide/
+│   ├── changelog.md
+│   ├── contributing.md
+│   └── gen_ref_pages.py    # Auto-generates API docs
+├── LICENSE                 # Your chosen license
+├── mkdocs.yml              # Documentation configuration
+├── pyproject.toml          # Project and tool configuration
+├── README.md               # Project documentation
+├── src/                    # Source code (src layout)
+│   └── your_package/
+│       ├── __init__.py
+│       ├── __main__.py     # CLI entry point
+│       ├── self_subcommand.py  # Built-in commands
+│       └── settings.py     # Configuration (optional)
+├── tests/                  # Test suite
+│   ├── __init__.py
+│   ├── conftest.py
+│   └── test_cli.py
+└── uv.lock                 # Dependency lock file
+```
+
+### Core Components
+
+#### Command Line Interface (CLI)
+Every package includes a fully functional CLI built with Typer:
+
+- **Main CLI**: Accessible via `python -m your_package` or `your_package`
+- **Built-in Commands**: Version, help, and self-diagnostics
+- **Extensible**: Easy to add new commands and subcommands
+- **Rich Output**: Beautiful help text and error messages
+
+#### Configuration Management
+Optional Pydantic Settings integration:
+
+```python
+# src/your_package/settings.py
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    debug: bool = False
+    log_level: str = "INFO"
+    
+    class Config:
+        env_prefix = "YOUR_PACKAGE_"
+```
+
+Usage:
+```console
+export YOUR_PACKAGE_DEBUG=true
+export YOUR_PACKAGE_LOG_LEVEL=DEBUG
+your_package command
+```
+
+#### Logging
+Loguru-based logging with optional file output:
+
+```python
+from loguru import logger
+
+logger.info("Application started")
+logger.debug("Debug information")
+logger.error("Something went wrong")
+```
+
+With file logging enabled:
+- Console output for development
+- Rotating log files for production
+- Structured logging with timestamps
+
+### Development Tools
+
+#### Poe The Poet Tasks
+Pre-configured tasks in `pyproject.toml`:
+
+```console
+# Code Quality
+poe ty              # Type checking with ty
+poe ruff-check      # Linting with ruff
+poe ruff-format     # Code formatting with ruff
+poe ruff            # Both linting and formatting
+poe check           # Quick quality checks
+poe qc              # Comprehensive quality control
+
+# Testing
+poe test            # Run pytest
+poe coverage        # Generate coverage report
+
+# Publishing
+poe publish_patch   # Patch version release (1.0.0 -> 1.0.1)
+poe publish_minor   # Minor version release (1.0.0 -> 1.1.0)
+poe publish_major   # Major version release (1.0.0 -> 2.0.0)
+poe publish         # Alias for publish_minor
+
+# Documentation
+poe docs-serve      # Serve docs locally
+poe docs-build      # Build documentation
+poe docs-deploy     # Deploy to GitHub Pages
+
+# Utilities
+poe clean           # Remove build artifacts
+poe tree            # Show project structure
+```
+
+#### Quality Assurance
+Comprehensive code quality tools:
+
+- **Ruff**: Lightning-fast linting and formatting
+- **ty**: Type checking for Python
+- **pytest**: Testing framework with fixtures
+- **Coverage**: Code coverage reporting
+
+### GitHub Integration
+
+#### Workflows
+Two main GitHub Actions workflows:
+
+**Release Workflow** (`release.yaml`):
+1. **Dynamic Python Version Detection**: Reads test versions from `pyproject.toml`
+2. **Matrix Testing**: Tests across Python versions and operating systems
+3. **Build Package**: Creates wheel and source distributions
+4. **Publish to PyPI**: Uses trusted publishing (no API tokens)
+5. **GitHub Release**: Auto-generates release notes and changelog
+6. **Deploy Documentation**: Triggers documentation deployment
+
+**Documentation Workflow** (`docs.yml`):
+1. **Auto-enable GitHub Pages**: Sets up Pages if not already configured
+2. **Build Documentation**: Compiles MkDocs site
+3. **Deploy**: Publishes to GitHub Pages
+
+#### Issue Templates
+Professional GitHub issue templates:
+
+- **Bug Report**: Structured bug reporting with environment details
+- **Feature Request**: Template for suggesting new features
+- **Question**: General questions and discussion
+- **Configuration**: Links to discussions and documentation
+
+#### Dependabot
+Automatic dependency updates:
+- **Python dependencies**: Daily checks
+- **GitHub Actions**: Weekly checks
+- **Grouped updates**: Related dependencies updated together
+
+### Documentation System
+
+#### MkDocs Integration
+Complete documentation setup with theme options:
+
+**Available Themes**:
+- **Material**: Feature-rich with dark/light mode
+- **Read the Docs**: Classic documentation style
+- **MkDocs**: Default lightweight theme
+- **Bootstrap**: Responsive design
+- **Windmill**: Clean minimal theme
+
+**Features**:
+- **Auto-generated API documentation** from docstrings
+- **Search functionality** with highlighting
+- **Automatic deployment** to GitHub Pages
+- **Navigation structure** with user guide and examples
+
+#### Documentation Structure
+```
+docs/
+├── index.md                # Homepage
+├── getting-started/
+│   ├── installation.md     # Installation instructions
+│   ├── quickstart.md       # Quick start guide
+│   └── configuration.md    # Configuration options
+├── user-guide/
+│   ├── cli.md             # CLI usage
+│   └── examples.md        # Usage examples
+├── contributing.md        # Contribution guidelines
+└── changelog.md           # Project changelog
+```
+
+## Configuration Options
+
+### Cookiecutter Variables
+
+#### Basic Project Information
+```json
+{
+    "package_name": "my_package",
+    "package_description": "A short description of the package",
+    "author_name": "Your Name", 
+    "author_email": "your.email@example.com",
+    "github_username": "yourusername",
+    "project_version": "0.1.0"
+}
+```
+
+#### License Options
+```json
+{
+    "license": [
+        "MIT",
+        "Apache-2.0", 
+        "GPL-3.0",
+        "BSD-2-Clause",
+        "BSD-3-Clause",
+        "BSL-1.0",
+        "CC0-1.0",
+        "EPL-2.0",
+        "GPL-2.0",
+        "LGPL-2.1",
+        "MPL-2.0",
+        "AGPL-3.0",
+        "no-license"
+    ]
+}
+```
+
+#### Feature Toggles
+```json
+{
+    "use_pydantic_settings": true,
+    "log_to_file": false,
+    "create_github_repo": false,
+    "make_github_repo_private": false,
+    "readme_badges": true
+}
+```
+
+#### Build and CI Configuration
+```json
+{
+    "build_backend": ["uv", "hatch"],
+    "python_version_dev": "3.13",
+    "python_testing_matrix": ["3.11", "3.12", "3.13"],
+    "os_testing_matrix": "ubuntu-latest, macos-latest, windows-latest"
+}
+```
+
+#### Documentation Options
+```json
+{
+    "mkdocs_theme": [
+        "material",
+        "readthedocs", 
+        "mkdocs",
+        "bootstrap",
+        "windmill"
+    ]
+}
+```
+
+### Advanced Configuration
+
+#### CI/CD Customization
+Modify Python versions and OS matrix in your project's `pyproject.toml`:
+
+```toml
+[tool.your_package.ci]
+test-python-versions = ["3.11", "3.12", "3.13"]
+```
+
+The workflow automatically detects and uses these versions.
+
+#### Build Backend Selection
+Choose between build backends:
+
+- **uv** (default): Fast, modern dependency resolution
+- **hatch**: Traditional, well-established build system
+
+## GitHub Actions Workflow Details
+
+### Workflow Triggers
+The release workflow triggers on:
+- **Semantic version tags**: `v1.0.0`, `v2.1.3`, etc.
+- **Pull requests**: Runs tests only
+- **Manual dispatch**: For testing
+
+### Workflow Jobs
+
+#### 1. Get Python Versions
+- Extracts Python test versions from `pyproject.toml`
+- Falls back to default versions if not specified
+- Outputs versions for matrix testing
+
+#### 2. Test Matrix
+- Tests across Python versions and operating systems
+- Runs comprehensive test suite
+- Checks code quality with ruff and ty
+
+#### 3. Build Package
+- Creates wheel and source distributions
+- Uploads artifacts for other jobs
+- Only runs on successful tests and version tags
+
+#### 4. Publish to PyPI
+- Uses PyPI trusted publishing (no API tokens needed)
+- Downloads build artifacts
+- Publishes to PyPI automatically
+
+#### 5. GitHub Release
+- Auto-generates changelog from git history
+- Creates GitHub release with notes
+- Attaches build artifacts
+- Only runs on successful publishing
+
+#### 6. Deploy Documentation
+- Triggers documentation workflow via repository dispatch
+- Ensures documentation updates after releases
+
+### Trusted Publishing Setup
+For PyPI publishing to work, configure trusted publishing:
+
+1. **Go to PyPI**: https://pypi.org/manage/account/publishing/
+2. **Add a new trusted publisher**:
+   - Repository name: `your-username/your-package`
+   - Workflow name: `release.yaml`
+   - Environment name: `pypi` (optional but recommended)
+
+## Next Steps
+
+- **[Customization Guide](customization.md)** - How to modify your generated project
+- **[Advanced Features](advanced.md)** - Power user features and tips
+- **[Contributing](../CONTRIBUTING.md)** - Contributing to the template itself
\ No newline at end of file

From 4ea17d931993f453550a8a921724cdeb06081ff3 Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:35:50 -0500
Subject: [PATCH 2/7] feat: add documentation poe tasks and mkdocs
 configuration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation management tasks:
- docs-serve: Serve documentation locally for development
- docs-build: Build documentation for production
- docs-deploy: Deploy documentation to GitHub Pages

Add mkdocs.yml configuration:
- Material theme with dark/light mode toggle
- Navigation structure for all documentation pages
- Search functionality and code highlighting
- Mermaid diagram support
- Responsive design features

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 mkdocs.yml     | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++
 pyproject.toml | 14 ++++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 mkdocs.yml

diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..93e7389
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,62 @@
+site_name: Python Package Cookiecutter Template
+site_description: A comprehensive cookiecutter template for modern Python packages
+site_url: https://jnyjny.github.io/python-package-cookiecutter/
+repo_url: https://github.com/JnyJny/python-package-cookiecutter
+repo_name: JnyJny/python-package-cookiecutter
+
+docs_dir: docs
+site_dir: site
+
+nav:
+  - Home: index.md
+  - Overview: overview.md
+  - Quick Start: quickstart.md
+  - Template Guide: template-guide.md
+  - Customization: customization.md
+
+theme:
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - attr_list
+  - md_in_html
+  - toc:
+      permalink: true
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index 49ac5a3..6ec8895 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -15,6 +15,9 @@ dev = [
     "sphinx>=8.2.3",
     "toml-cli",
 ]
+docs = [
+    "mkdocs>=1.6.1",
+]
 
 [tool.poe.tasks]
 
@@ -86,6 +89,17 @@ _remove_gh_repo = "gh repo delete thing --yes"
 clean.sequence = ["_remove_tmp", "_remove_gh_repo" ]
 clean.help = "Cleanup project."
 
+# Documentation tasks
+
+docs-serve.cmd = "mkdocs serve"
+docs-serve.help = "[Documentation] Serve documentation locally for development."
+
+docs-build.cmd = "mkdocs build"
+docs-build.help = "[Documentation] Build documentation for production."
+
+docs-deploy.cmd = "mkdocs gh-deploy --force"
+docs-deploy.help = "[Documentation] Deploy documentation to GitHub Pages."
+
 # Misc
 
 tree.cmd = "tree . -a -I .venv -I .git -I .ruff_cache -I .pytest_cache"

From 82adccc260252af237a2f0340d9a133fa4c8f89b Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:36:46 -0500
Subject: [PATCH 3/7] style: shorten poe task help messages for docs tasks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace "Documentation" with "Docs" in help messages for brevity:
- docs-serve: "[Docs] Serve docs locally for development."
- docs-build: "[Docs] Build docs for production."
- docs-deploy: "[Docs] Deploy docs to GitHub Pages."

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 pyproject.toml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 6ec8895..fe7f315 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -92,13 +92,13 @@ clean.help = "Cleanup project."
 # Documentation tasks
 
 docs-serve.cmd = "mkdocs serve"
-docs-serve.help = "[Documentation] Serve documentation locally for development."
+docs-serve.help = "[Docs] Serve docs locally for development."
 
 docs-build.cmd = "mkdocs build"
-docs-build.help = "[Documentation] Build documentation for production."
+docs-build.help = "[Docs] Build docs for production."
 
 docs-deploy.cmd = "mkdocs gh-deploy --force"
-docs-deploy.help = "[Documentation] Deploy documentation to GitHub Pages."
+docs-deploy.help = "[Docs] Deploy docs to GitHub Pages."
 
 # Misc
 

From 7a5396f7d6fc12977d75bfedb3789895a07e33e6 Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:40:11 -0500
Subject: [PATCH 4/7] fix: resolve mkdocs build errors and warnings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add missing documentation dependencies:
- mkdocs-material>=9.5.0 for Material theme
- pymdown-extensions>=10.0.0 for enhanced markdown features

Fix broken documentation links:
- Remove references to non-existent workflows.md and advanced.md
- Update CONTRIBUTING.md references to avoid broken links
- Maintain clear navigation while removing invalid targets

MkDocs now builds successfully with only expected README.md warning.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/index.md          | 2 +-
 docs/quickstart.md     | 2 +-
 docs/template-guide.md | 4 +---
 pyproject.toml         | 2 ++
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 2cb5489..358383a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -74,7 +74,7 @@ your-package/
 
 - **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/JnyJny/python-package-cookiecutter/issues)
 - **Discussions**: Ask questions on [GitHub Discussions](https://github.com/JnyJny/python-package-cookiecutter/discussions)
-- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines
+- **Contributing**: See the project's CONTRIBUTING.md for contribution guidelines
 
 ## License
 
diff --git a/docs/quickstart.md b/docs/quickstart.md
index fc65e1c..36e8285 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -194,7 +194,7 @@ poe publish_patch
 
 - **[Template User Guide](template-guide.md)** - Detailed feature documentation
 - **[Customization Guide](customization.md)** - Modify your project
-- **[GitHub Workflows](workflows.md)** - Understanding the CI/CD pipeline
+- **GitHub Workflows** - See template-guide.md for CI/CD pipeline details
 
 ## Troubleshooting
 
diff --git a/docs/template-guide.md b/docs/template-guide.md
index 2ababa9..4dd789b 100644
--- a/docs/template-guide.md
+++ b/docs/template-guide.md
@@ -344,6 +344,4 @@ For PyPI publishing to work, configure trusted publishing:
 
 ## Next Steps
 
-- **[Customization Guide](customization.md)** - How to modify your generated project
-- **[Advanced Features](advanced.md)** - Power user features and tips
-- **[Contributing](../CONTRIBUTING.md)** - Contributing to the template itself
\ No newline at end of file
+- **[Customization Guide](customization.md)** - How to modify your generated project
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index fe7f315..cdd72a8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,6 +17,8 @@ dev = [
 ]
 docs = [
     "mkdocs>=1.6.1",
+    "mkdocs-material>=9.5.0",
+    "pymdown-extensions>=10.0.0",
 ]
 
 [tool.poe.tasks]

From b3dd045e1aedd3bc83f82b2abea1f8e8e947e37f Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:44:49 -0500
Subject: [PATCH 5/7] docs: remove marketing-style adjectives and use concrete
 descriptive terms
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace subjective quality terms with specific, functional descriptions:
- "beautiful" → "formatted" or "structured"
- "professional" → "structured"
- "modern" → removed (use "Python Ecosystem" instead)
- "lightning-fast" → "fast"
- "seamless" → "streamlined"
- "full-featured" → "complete"

Focus on concrete benefits and technical features rather than
subjective quality assessments that may not age well.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/index.md          | 10 +++++-----
 docs/overview.md       |  8 ++++----
 docs/template-guide.md |  8 ++++----
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 358383a..324bcec 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,14 +20,14 @@ Welcome to the comprehensive documentation for the Python Package Cookiecutter T
 - Documentation auto-deployed to GitHub Pages
 - Quality tools pre-configured: ruff, ty, pytest, coverage reporting
 
-### Modern Python Ecosystem
-- **[uv](https://docs.astral.sh/uv/)** for lightning-fast dependency management
+### Python Ecosystem
+- **[uv](https://docs.astral.sh/uv/)** for fast dependency management
 - **[Typer](https://typer.tiangolo.com)** CLI framework with rich help
-- **[Loguru](https://loguru.readthedocs.io/en/stable/)** for beautiful logging
+- **[Loguru](https://loguru.readthedocs.io/en/stable/)** for structured logging
 - **[Pydantic Settings](https://docs.pydantic.dev/latest/api/pydantic_settings/)** for configuration
 - **[MkDocs](https://www.mkdocs.org/)** with multiple theme options
 
-### Professional Package Structure
+### Package Structure
 - **src/ layout** following Python packaging best practices
 - **Comprehensive testing** setup with pytest and coverage
 - **Multiple build backends** (uv or hatch)
@@ -48,7 +48,7 @@ Welcome to the comprehensive documentation for the Python Package Cookiecutter T
 
 ## Template Workflow
 
-The template enables a seamless development workflow:
+The template enables a streamlined development workflow:
 
 1. **Write Code** - Edit your package source files
 2. **Quality Control** - Run `poe qc` to check code quality
diff --git a/docs/overview.md b/docs/overview.md
index 4e6b36d..12dda27 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -4,7 +4,7 @@
 
 There are many [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/index.html) 
 [templates](https://www.cookiecutter.io/templates), but this one is mine and I'm sharing 
-it with you. With it, you can quickly create a full-featured Python package designed to 
+it with you. With it, you can quickly create a complete Python package designed to 
 be managed with [uv](https://docs.astral.sh/uv/) and 
 [direnv](https://direnv.net), a default [typer](https://typer.tiangolo.com) 
 command-line interface, optional settings using 
@@ -26,10 +26,10 @@ with your project repository.
 - **Quality tools pre-configured**: ruff, ty, pytest, coverage reporting
 
 ### Python Ecosystem
-- **[uv](https://docs.astral.sh/uv/)** for lightning-fast dependency management and 
+- **[uv](https://docs.astral.sh/uv/)** for fast dependency management and 
   Python version control
 - **[Typer](https://typer.tiangolo.com)** CLI framework with rich help and autocompletion
-- **[Loguru](https://loguru.readthedocs.io/en/stable/)** for beautiful, structured logging
+- **[Loguru](https://loguru.readthedocs.io/en/stable/)** for structured logging
 - **[Pydantic Settings](https://docs.pydantic.dev/latest/api/pydantic_settings/)** for 
   configuration management
 - **[MkDocs](https://www.mkdocs.org/)** with multiple theme options for documentation
@@ -41,7 +41,7 @@ with your project repository.
 - **Semantic versioning** with automated changelog generation
 - **Cross-platform testing** (Linux, macOS, Windows)
 
-### Seamless Workflow
+### Streamlined Workflow
 - **Write Code** - Edit your package source files
 - **Quality Control** - Run `poe qc` to check code quality
 - **Release** - Run `poe publish` to version and tag
diff --git a/docs/template-guide.md b/docs/template-guide.md
index 4dd789b..8290983 100644
--- a/docs/template-guide.md
+++ b/docs/template-guide.md
@@ -57,7 +57,7 @@ Every package includes a fully functional CLI built with Typer:
 - **Main CLI**: Accessible via `python -m your_package` or `your_package`
 - **Built-in Commands**: Version, help, and self-diagnostics
 - **Extensible**: Easy to add new commands and subcommands
-- **Rich Output**: Beautiful help text and error messages
+- **Rich Output**: Formatted help text and error messages
 
 #### Configuration Management
 Optional Pydantic Settings integration:
@@ -134,7 +134,7 @@ poe tree            # Show project structure
 #### Quality Assurance
 Comprehensive code quality tools:
 
-- **Ruff**: Lightning-fast linting and formatting
+- **Ruff**: Fast linting and formatting
 - **ty**: Type checking for Python
 - **pytest**: Testing framework with fixtures
 - **Coverage**: Code coverage reporting
@@ -158,7 +158,7 @@ Two main GitHub Actions workflows:
 3. **Deploy**: Publishes to GitHub Pages
 
 #### Issue Templates
-Professional GitHub issue templates:
+Structured GitHub issue templates:
 
 - **Bug Report**: Structured bug reporting with environment details
 - **Feature Request**: Template for suggesting new features
@@ -290,7 +290,7 @@ The workflow automatically detects and uses these versions.
 #### Build Backend Selection
 Choose between build backends:
 
-- **uv** (default): Fast, modern dependency resolution
+- **uv** (default): Fast dependency resolution
 - **hatch**: Traditional, well-established build system
 
 ## GitHub Actions Workflow Details

From 4aa2340d5b0c808c1930cf5d28a64718e2056cef Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:48:34 -0500
Subject: [PATCH 6/7] ci: Updated .envrc to auto uv sync all groups

---
 .envrc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.envrc b/.envrc
index 327659f..4892f47 100644
--- a/.envrc
+++ b/.envrc
@@ -1,2 +1,2 @@
-uv sync
+uv sync --all-groups
 source_env .venv/bin/activate

From 8909155c2a334cb4f2d292a4972bb3b293eb0495 Mon Sep 17 00:00:00 2001
From: JnyJny <erik.oshaughnessy@gmail.com>
Date: Sun, 27 Jul 2025 11:49:03 -0500
Subject: [PATCH 7/7] docs: Updated docs group dependencies

---
 uv.lock | 196 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 196 insertions(+)

diff --git a/uv.lock b/uv.lock
index 40cf9e2..26c7f12 100644
--- a/uv.lock
+++ b/uv.lock
@@ -33,6 +33,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" },
 ]
 
+[[package]]
+name = "backrefs"
+version = "5.9"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/eb/a7/312f673df6a79003279e1f55619abbe7daebbb87c17c976ddc0345c04c7b/backrefs-5.9.tar.gz", hash = "sha256:808548cb708d66b82ee231f962cb36faaf4f2baab032f2fbb783e9c2fdddaa59", size = 5765857, upload-time = "2025-06-22T19:34:13.97Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/19/4d/798dc1f30468134906575156c089c492cf79b5a5fd373f07fe26c4d046bf/backrefs-5.9-py310-none-any.whl", hash = "sha256:db8e8ba0e9de81fcd635f440deab5ae5f2591b54ac1ebe0550a2ca063488cd9f", size = 380267, upload-time = "2025-06-22T19:34:05.252Z" },
+    { url = "https://files.pythonhosted.org/packages/55/07/f0b3375bf0d06014e9787797e6b7cc02b38ac9ff9726ccfe834d94e9991e/backrefs-5.9-py311-none-any.whl", hash = "sha256:6907635edebbe9b2dc3de3a2befff44d74f30a4562adbb8b36f21252ea19c5cf", size = 392072, upload-time = "2025-06-22T19:34:06.743Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/12/4f345407259dd60a0997107758ba3f221cf89a9b5a0f8ed5b961aef97253/backrefs-5.9-py312-none-any.whl", hash = "sha256:7fdf9771f63e6028d7fee7e0c497c81abda597ea45d6b8f89e8ad76994f5befa", size = 397947, upload-time = "2025-06-22T19:34:08.172Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/fa31834dc27a7f05e5290eae47c82690edc3a7b37d58f7fb35a1bdbf355b/backrefs-5.9-py313-none-any.whl", hash = "sha256:cc37b19fa219e93ff825ed1fed8879e47b4d89aa7a1884860e2db64ccd7c676b", size = 399843, upload-time = "2025-06-22T19:34:09.68Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/24/b29af34b2c9c41645a9f4ff117bae860291780d73880f449e0b5d948c070/backrefs-5.9-py314-none-any.whl", hash = "sha256:df5e169836cc8acb5e440ebae9aad4bf9d15e226d3bad049cf3f6a5c20cc8dc9", size = 411762, upload-time = "2025-06-22T19:34:11.037Z" },
+    { url = "https://files.pythonhosted.org/packages/41/ff/392bff89415399a979be4a65357a41d92729ae8580a66073d8ec8d810f98/backrefs-5.9-py39-none-any.whl", hash = "sha256:f48ee18f6252b8f5777a22a00a09a85de0ca931658f1dd96d4406a34f3748c60", size = 380265, upload-time = "2025-06-22T19:34:12.405Z" },
+]
+
 [[package]]
 name = "binaryornot"
 version = "0.4.4"
@@ -134,6 +148,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8f/d7/9322c609343d929e75e7e5e6255e614fcc67572cfd083959cdef3b7aad79/docutils-0.21.2-py3-none-any.whl", hash = "sha256:dafca5b9e384f0e419294eb4d2ff9fa826435bf15f15b7bd45723e8ad76811b2", size = 587408, upload-time = "2024-04-23T18:57:14.835Z" },
 ]
 
+[[package]]
+name = "ghp-import"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "python-dateutil" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz", hash = "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343", size = 10943, upload-time = "2022-05-02T15:47:16.11Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" },
+]
+
 [[package]]
 name = "idna"
 version = "3.10"
@@ -182,6 +208,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/31/b4/b9b800c45527aadd64d5b442f9b932b00648617eb5d63d2c7a6587b7cafc/jmespath-1.0.1-py3-none-any.whl", hash = "sha256:02e2e4cc71b5bcab88332eebf907519190dd9e6e82107fa7f83b1003a6252980", size = 20256, upload-time = "2022-06-17T18:00:10.251Z" },
 ]
 
+[[package]]
+name = "markdown"
+version = "3.8.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d7/c2/4ab49206c17f75cb08d6311171f2d65798988db4360c4d1485bd0eedd67c/markdown-3.8.2.tar.gz", hash = "sha256:247b9a70dd12e27f67431ce62523e675b866d254f900c4fe75ce3dda62237c45", size = 362071, upload-time = "2025-06-19T17:12:44.483Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/96/2b/34cc11786bc00d0f04d0f5fdc3a2b1ae0b6239eef72d3d345805f9ad92a1/markdown-3.8.2-py3-none-any.whl", hash = "sha256:5c83764dbd4e00bdd94d85a19b8d55ccca20fe35b2e678a1422b380324dd5f24", size = 106827, upload-time = "2025-06-19T17:12:42.994Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "3.0.0"
@@ -231,6 +266,84 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
 ]
 
+[[package]]
+name = "mergedeep"
+version = "1.3.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3a/41/580bb4006e3ed0361b8151a01d324fb03f420815446c7def45d02f74c270/mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8", size = 4661, upload-time = "2021-02-05T18:55:30.623Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" },
+]
+
+[[package]]
+name = "mkdocs"
+version = "1.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "ghp-import" },
+    { name = "jinja2" },
+    { name = "markdown" },
+    { name = "markupsafe" },
+    { name = "mergedeep" },
+    { name = "mkdocs-get-deps" },
+    { name = "packaging" },
+    { name = "pathspec" },
+    { name = "pyyaml" },
+    { name = "pyyaml-env-tag" },
+    { name = "watchdog" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bc/c6/bbd4f061bd16b378247f12953ffcb04786a618ce5e904b8c5a01a0309061/mkdocs-1.6.1.tar.gz", hash = "sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2", size = 3889159, upload-time = "2024-08-30T12:24:06.899Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl", hash = "sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e", size = 3864451, upload-time = "2024-08-30T12:24:05.054Z" },
+]
+
+[[package]]
+name = "mkdocs-get-deps"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mergedeep" },
+    { name = "platformdirs" },
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/98/f5/ed29cd50067784976f25ed0ed6fcd3c2ce9eb90650aa3b2796ddf7b6870b/mkdocs_get_deps-0.2.0.tar.gz", hash = "sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c", size = 10239, upload-time = "2023-11-20T17:51:09.981Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl", hash = "sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134", size = 9521, upload-time = "2023-11-20T17:51:08.587Z" },
+]
+
+[[package]]
+name = "mkdocs-material"
+version = "9.6.16"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "babel" },
+    { name = "backrefs" },
+    { name = "colorama" },
+    { name = "jinja2" },
+    { name = "markdown" },
+    { name = "mkdocs" },
+    { name = "mkdocs-material-extensions" },
+    { name = "paginate" },
+    { name = "pygments" },
+    { name = "pymdown-extensions" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/dd/84/aec27a468c5e8c27689c71b516fb5a0d10b8fca45b9ad2dd9d6e43bc4296/mkdocs_material-9.6.16.tar.gz", hash = "sha256:d07011df4a5c02ee0877496d9f1bfc986cfb93d964799b032dd99fe34c0e9d19", size = 4028828, upload-time = "2025-07-26T15:53:47.542Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/65/f4/90ad67125b4dd66e7884e4dbdfab82e3679eb92b751116f8bb25ccfe2f0c/mkdocs_material-9.6.16-py3-none-any.whl", hash = "sha256:8d1a1282b892fe1fdf77bfeb08c485ba3909dd743c9ba69a19a40f637c6ec18c", size = 9223743, upload-time = "2025-07-26T15:53:44.236Z" },
+]
+
+[[package]]
+name = "mkdocs-material-extensions"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/79/9b/9b4c96d6593b2a541e1cb8b34899a6d021d208bb357042823d4d2cabdbe7/mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443", size = 11847, upload-time = "2023-11-22T19:09:45.208Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" },
+]
+
 [[package]]
 name = "packaging"
 version = "25.0"
@@ -240,6 +353,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" },
 ]
 
+[[package]]
+name = "paginate"
+version = "0.5.7"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ec/46/68dde5b6bc00c1296ec6466ab27dddede6aec9af1b99090e1107091b3b84/paginate-0.5.7.tar.gz", hash = "sha256:22bd083ab41e1a8b4f3690544afb2c60c25e5c9a63a30fa2f483f6c60c8e5945", size = 19252, upload-time = "2024-08-25T14:17:24.139Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/90/96/04b8e52da071d28f5e21a805b19cb9390aa17a47462ac87f5e2696b9566d/paginate-0.5.7-py2.py3-none-any.whl", hash = "sha256:b885e2af73abcf01d9559fd5216b57ef722f8c42affbb63942377668e35c7591", size = 13746, upload-time = "2024-08-25T14:17:22.55Z" },
+]
+
 [[package]]
 name = "pastel"
 version = "0.2.1"
@@ -249,6 +371,24 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/aa/18/a8444036c6dd65ba3624c63b734d3ba95ba63ace513078e1580590075d21/pastel-0.2.1-py2.py3-none-any.whl", hash = "sha256:4349225fcdf6c2bb34d483e523475de5bb04a5c10ef711263452cb37d7dd4364", size = 5955, upload-time = "2020-09-16T19:21:11.409Z" },
 ]
 
+[[package]]
+name = "pathspec"
+version = "0.12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712", size = 51043, upload-time = "2023-12-10T22:30:45Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08", size = 31191, upload-time = "2023-12-10T22:30:43.14Z" },
+]
+
+[[package]]
+name = "platformdirs"
+version = "4.3.8"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fe/8b/3c73abc9c759ecd3f1f7ceff6685840859e8070c4d947c93fae71f6a0bf2/platformdirs-4.3.8.tar.gz", hash = "sha256:3d512d96e16bcb959a814c9f348431070822a6496326a4be0911c40b5a74c2bc", size = 21362, upload-time = "2025-05-07T22:47:42.121Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fe/39/979e8e21520d4e47a0bbe349e2713c0aac6f3d853d0e5b34d76206c439aa/platformdirs-4.3.8-py3-none-any.whl", hash = "sha256:ff7059bb7eb1179e2685604f4aaf157cfd9535242bd23742eadc3c13542139b4", size = 18567, upload-time = "2025-05-07T22:47:40.376Z" },
+]
+
 [[package]]
 name = "pluggy"
 version = "1.6.0"
@@ -280,6 +420,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8a/0b/9fcc47d19c48b59121088dd6da2488a49d5f72dacf8262e2790a1d2c7d15/pygments-2.19.1-py3-none-any.whl", hash = "sha256:9ea1544ad55cecf4b8242fab6dd35a93bbce657034b0611ee383099054ab6d8c", size = 1225293, upload-time = "2025-01-06T17:26:25.553Z" },
 ]
 
+[[package]]
+name = "pymdown-extensions"
+version = "10.16"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown" },
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1a/0a/c06b542ac108bfc73200677309cd9188a3a01b127a63f20cadc18d873d88/pymdown_extensions-10.16.tar.gz", hash = "sha256:71dac4fca63fabeffd3eb9038b756161a33ec6e8d230853d3cecf562155ab3de", size = 853197, upload-time = "2025-06-21T17:56:36.974Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/d4/10bb14004d3c792811e05e21b5e5dcae805aacb739bd12a0540967b99592/pymdown_extensions-10.16-py3-none-any.whl", hash = "sha256:f5dd064a4db588cb2d95229fc4ee63a1b16cc8b4d0e6145c0899ed8723da1df2", size = 266143, upload-time = "2025-06-21T17:56:35.356Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "8.4.0"
@@ -322,6 +475,11 @@ dev = [
     { name = "sphinx" },
     { name = "toml-cli" },
 ]
+docs = [
+    { name = "mkdocs" },
+    { name = "mkdocs-material" },
+    { name = "pymdown-extensions" },
+]
 
 [package.metadata]
 
@@ -334,6 +492,11 @@ dev = [
     { name = "sphinx", specifier = ">=8.2.3" },
     { name = "toml-cli" },
 ]
+docs = [
+    { name = "mkdocs", specifier = ">=1.6.1" },
+    { name = "mkdocs-material", specifier = ">=9.5.0" },
+    { name = "pymdown-extensions", specifier = ">=10.0.0" },
+]
 
 [[package]]
 name = "python-slugify"
@@ -364,6 +527,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/fa/de/02b54f42487e3d3c6efb3f89428677074ca7bf43aae402517bc7cca949f3/PyYAML-6.0.2-cp313-cp313-win_amd64.whl", hash = "sha256:8388ee1976c416731879ac16da0aff3f63b286ffdd57cdeb95f3f2e085687563", size = 156446, upload-time = "2024-08-06T20:33:04.33Z" },
 ]
 
+[[package]]
+name = "pyyaml-env-tag"
+version = "1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/eb/2e/79c822141bfd05a853236b504869ebc6b70159afc570e1d5a20641782eaa/pyyaml_env_tag-1.1.tar.gz", hash = "sha256:2eb38b75a2d21ee0475d6d97ec19c63287a7e140231e4214969d0eac923cd7ff", size = 5737, upload-time = "2025-05-13T15:24:01.64Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/11/432f32f8097b03e3cd5fe57e88efb685d964e2e5178a48ed61e841f7fdce/pyyaml_env_tag-1.1-py3-none-any.whl", hash = "sha256:17109e1a528561e32f026364712fee1264bc2ea6715120891174ed1b980d2e04", size = 4722, upload-time = "2025-05-13T15:23:59.629Z" },
+]
+
 [[package]]
 name = "regex"
 version = "2024.11.6"
@@ -632,3 +807,24 @@ sdist = { url = "https://files.pythonhosted.org/packages/15/22/9ee70a2574a4f4599
 wheels = [
     { url = "https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl", hash = "sha256:e6b01673c0fa6a13e374b50871808eb3bf7046c4b125b216f6bf1cc604cff0dc", size = 129795, upload-time = "2025-06-18T14:07:40.39Z" },
 ]
+
+[[package]]
+name = "watchdog"
+version = "6.0.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz", hash = "sha256:9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282", size = 131220, upload-time = "2024-11-01T14:07:13.037Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/68/98/b0345cabdce2041a01293ba483333582891a3bd5769b08eceb0d406056ef/watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:490ab2ef84f11129844c23fb14ecf30ef3d8a6abafd3754a6f75ca1e6654136c", size = 96480, upload-time = "2024-11-01T14:06:42.952Z" },
+    { url = "https://files.pythonhosted.org/packages/85/83/cdf13902c626b28eedef7ec4f10745c52aad8a8fe7eb04ed7b1f111ca20e/watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:76aae96b00ae814b181bb25b1b98076d5fc84e8a53cd8885a318b42b6d3a5134", size = 88451, upload-time = "2024-11-01T14:06:45.084Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/c4/225c87bae08c8b9ec99030cd48ae9c4eca050a59bf5c2255853e18c87b50/watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a175f755fc2279e0b7312c0035d52e27211a5bc39719dd529625b1930917345b", size = 89057, upload-time = "2024-11-01T14:06:47.324Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/c7/ca4bf3e518cb57a686b2feb4f55a1892fd9a3dd13f470fca14e00f80ea36/watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7607498efa04a3542ae3e05e64da8202e58159aa1fa4acddf7678d34a35d4f13", size = 79079, upload-time = "2024-11-01T14:06:59.472Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/51/d46dc9332f9a647593c947b4b88e2381c8dfc0942d15b8edc0310fa4abb1/watchdog-6.0.0-py3-none-manylinux2014_armv7l.whl", hash = "sha256:9041567ee8953024c83343288ccc458fd0a2d811d6a0fd68c4c22609e3490379", size = 79078, upload-time = "2024-11-01T14:07:01.431Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/57/04edbf5e169cd318d5f07b4766fee38e825d64b6913ca157ca32d1a42267/watchdog-6.0.0-py3-none-manylinux2014_i686.whl", hash = "sha256:82dc3e3143c7e38ec49d61af98d6558288c415eac98486a5c581726e0737c00e", size = 79076, upload-time = "2024-11-01T14:07:02.568Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/cc/da8422b300e13cb187d2203f20b9253e91058aaf7db65b74142013478e66/watchdog-6.0.0-py3-none-manylinux2014_ppc64.whl", hash = "sha256:212ac9b8bf1161dc91bd09c048048a95ca3a4c4f5e5d4a7d1b1a7d5752a7f96f", size = 79077, upload-time = "2024-11-01T14:07:03.893Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/3b/b8964e04ae1a025c44ba8e4291f86e97fac443bca31de8bd98d3263d2fcf/watchdog-6.0.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:e3df4cbb9a450c6d49318f6d14f4bbc80d763fa587ba46ec86f99f9e6876bb26", size = 79078, upload-time = "2024-11-01T14:07:05.189Z" },
+    { url = "https://files.pythonhosted.org/packages/62/ae/a696eb424bedff7407801c257d4b1afda455fe40821a2be430e173660e81/watchdog-6.0.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:2cce7cfc2008eb51feb6aab51251fd79b85d9894e98ba847408f662b3395ca3c", size = 79077, upload-time = "2024-11-01T14:07:06.376Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/e8/dbf020b4d98251a9860752a094d09a65e1b436ad181faf929983f697048f/watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2", size = 79078, upload-time = "2024-11-01T14:07:07.547Z" },
+    { url = "https://files.pythonhosted.org/packages/07/f6/d0e5b343768e8bcb4cda79f0f2f55051bf26177ecd5651f84c07567461cf/watchdog-6.0.0-py3-none-win32.whl", hash = "sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a", size = 79065, upload-time = "2024-11-01T14:07:09.525Z" },
+    { url = "https://files.pythonhosted.org/packages/db/d9/c495884c6e548fce18a8f40568ff120bc3a4b7b99813081c8ac0c936fa64/watchdog-6.0.0-py3-none-win_amd64.whl", hash = "sha256:cbafb470cf848d93b5d013e2ecb245d4aa1c8fd0504e863ccefa32445359d680", size = 79070, upload-time = "2024-11-01T14:07:10.686Z" },
+    { url = "https://files.pythonhosted.org/packages/33/e8/e40370e6d74ddba47f002a32919d91310d6074130fe4e17dabcafc15cbf1/watchdog-6.0.0-py3-none-win_ia64.whl", hash = "sha256:a1914259fa9e1454315171103c6a30961236f508b9b623eae470268bbcc6a22f", size = 79067, upload-time = "2024-11-01T14:07:11.845Z" },
+]