feat: Add optional MkDocs documentation setup with Material theme

[safurrier]

Summary

Add comprehensive MkDocs documentation system that integrates seamlessly with the make init process as an optional (default-on) feature.

🎯 Key Features

✅ Seamless Integration

• Part of make init workflow: Prompted after example code choice
• Default "Yes": Encourages documentation but fully optional
• Auto-detection: Extracts GitHub username from git config
• Zero impact: Projects that skip docs work exactly as before

✅ Generic Template System

• Placeholder-based templates: {project_name}, {author_name}, {project_module_name}, etc.
• Project-specific generation: Creates docs for the actual project, not the template
• Future-proof: Templates update as the main template evolves
• Complete setup: mkdocs.yml, docs structure, GitHub Actions workflow

✅ Professional Documentation

• MkDocs + Material theme: Modern, responsive documentation
• Auto-generated API docs: mkdocstrings integration with Google-style docstrings
• GitHub Pages ready: Automatic deployment workflow included
• Local development: Hot-reload server with make docs-serve

🚀 User Experience

# User creates project from template
git clone https://github.com/user/awesome-project.git
cd awesome-project

# Interactive setup
make init
# → Project name: "Awesome ML Library"
# → Description: "Machine learning utilities" 
# → Documentation setup? (Y/n): [y] ← NEW optional step
# → ✅ Creates project-specific documentation

# Result: Professional docs ready to use
make docs-serve  # → http://localhost:8000

🛠️ What Gets Generated

When users choose "yes" for documentation:

awesome-ml-library/                    # ← User's project name
├── awesome_ml_library/               # ← User's module  
├── docs/
│   ├── index.md                     # ← "Awesome ML Library" homepage
│   ├── getting-started.md           # ← How to use the ML library
│   └── reference/api.md             # ← Auto-gen API docs
├── mkdocs.yml                       # ← Customized site config
└── .github/workflows/docs.yml       # ← Auto-deployment workflow

📁 Implementation Details

New Files

• templates/: Placeholder-based template files
  • mkdocs.yml.template
  • docs/index.md.template
  • docs/getting-started.md.template
  • docs/reference/api.md.template
  • .github/workflows/docs.yml.template

Enhanced Files

• scripts/init_project.py: Added setup_documentation() function
• Makefile: Added docs targets (install, build, serve, check, clean)
• docs/: Updated to describe template usage vs. project usage
• tests/test_docs_setup.py: Comprehensive conditional test coverage

Integration Points

• Dependency management: Conditional addition to dependency-groups.dev
• Quality checks: All existing tests and linting pass
• GitHub Actions: uv-integrated workflow for deployment

🧪 Testing

• ✅ Conditional tests: Work with or without docs enabled
• ✅ Template validation: Ensures all template files exist
• ✅ Quality gates: All linting, formatting, type checking pass
• ✅ Build verification: Documentation builds successfully

📊 Benefits

1. Professional appearance: Every project gets beautiful, searchable docs
2. Low maintenance: Auto-generated API docs + simple structure
3. Developer friendly: Local development server with hot reload
4. GitHub Pages ready: Automatic deployment on main branch pushes
5. Template evolution: Documentation setup improves over time
6. Proven patterns: Based on working setups from real projects

🔄 Backward Compatibility

• Zero breaking changes: Existing template usage unchanged
• Optional feature: Default "yes" but fully skippable
• Conditional logic: Tests and features adapt to docs presence/absence
• Clean fallback: Projects without docs work exactly as before

This enhancement significantly increases the value proposition of the template by providing professional documentation setup out of the box while maintaining complete flexibility for projects that don't need it.

🤖 Generated with Claude Code