Documentation Consolidation Assessment & Implementation Plan¶

Date: 2025-11-12 Project: S5 Slidefactory Goal: Create living documentation using MkDocs with auto-generation from source code

Executive Summary¶

This document provides a comprehensive assessment of the current documentation state and a detailed plan to consolidate it into a living documentation system using MkDocs Material theme. The core principle is: documentation should live in the source code and be auto-generated, with minimal handwritten guides only where necessary.

Key Metrics¶

Current State: - 📚 60 markdown files (28,000+ lines) across .claude/DOCUMENTATION and .claude/REPORTS - 💻 119 Python files with 79.8% function documentation, 63.8% class documentation - 🔌 192 API endpoints already auto-documented via FastAPI OpenAPI - 📊 90% type hint coverage enabling rich auto-documentation - ❌ No docs/ directory - needs to be created

Target State: - 📖 Single MkDocs site with auto-generated content from source code - 🔄 Live updates as code changes (via CI/CD) - 📝 ~10-15 essential markdown guides (down from 60) - 🤖 Auto-generated: API docs, module docs, schemas, database models - 🎨 Modern UI with Material for MkDocs (Shadcn-inspired styling)

Current Documentation Inventory¶

1. Handwritten Markdown Documentation¶

Root Level (3 files)¶

• CLAUDE.md (420 lines) - Developer guide for Claude Code
• README.md (443 lines) - Project overview and quick start
• ROADMAP.md (417 lines) - Feature roadmap

.claude/DOCUMENTATION/ (9 files, 4,091 lines)¶

User-facing guides: - USER_MANAGEMENT.md (1,240 lines) - USER_MANAGEMENT_QUICKREF.md (310 lines) - N8N_INTEGRATION.md (579 lines) - BRANDING.md (384 lines) - WHITELABEL_QUICKSTART.md (140 lines) - DEPLOYMENT_CHECKLIST.md (547 lines) - MIGRATION_GUIDE_LOCAL.md (321 lines) - TESTING_GUIDE.md (445 lines) - README.md (125 lines) - Navigation hub

.claude/REPORTS/ (51 files, 23,713 lines)¶

Technical implementation reports (2025-10-13 to 2025-11-05): - Infrastructure & Configuration (12 reports) - Database & Migrations (5 reports) - User Management & Authentication (8 reports) - Workflow Engine System (8 reports) - Whitelabel & Branding (3 reports) - UI & Frontend (6 reports) - Code Quality & Cleanup (7 reports) - Documentation & Guides (2+ reports)

2. Code-Based Documentation (Living in Source)¶

Already Well-Documented¶

✅ FastAPI OpenAPI (192 endpoints) - /docs, /redoc, /openapi.json ✅ Pydantic Schemas (30+ models) - Field descriptions, examples, validation ✅ Workflow Engine (98% coverage) - Base classes, implementations ✅ File Manager (98% coverage) - Storage abstractions ✅ N8N Manager (100% coverage) - Process tracking

Needs Documentation Work¶

❌ Context Module (9.1% file docs) - RAG/vector search system ❌ Auth Module (15% class docs) - Session management ❌ Utility Module (26% file docs) - 23 utility files ❌ Main Application (31% coverage) - App startup, middleware

3. Auto-Generated Potential¶

These can be generated from code: - API Reference (from FastAPI + docstrings) - Module Documentation (from Python docstrings) - Database Schema (from SQLAlchemy models) - Configuration Reference (from Pydantic Settings) - Type Reference (from type hints) - Workflow Engine Interfaces (from abstract base classes)

Assessment: What Should Be Documentation?¶

✅ Keep as Markdown (Essential Guides)¶

These require human context and cannot be auto-generated:

1. Getting Started (~200 lines)
2. Quick start guide
3. Installation instructions

4. First steps tutorial

5. User Guides (~800 lines total)

6. User Management Guide (consolidated from 1,240 lines)
7. N8N Integration Guide (consolidated from 579 lines)

8. Whitelabel/Branding Guide (consolidated from 384 lines)

9. Developer Guides (~600 lines total)

10. Architecture Overview
11. Development Workflow
12. Testing Guide (consolidated from 445 lines)

13. Deployment Guide (consolidated from 547 lines)

14. Operations (~300 lines total)

15. Configuration Reference (supplement to auto-generated)
16. Troubleshooting Guide

17. Production Deployment Checklist

18. Project (~200 lines total)

19. Roadmap (from ROADMAP.md)
20. Contributing Guidelines
21. Changelog

Total: ~2,100 lines of handwritten docs (down from 28,000 lines)

🤖 Auto-Generate from Source Code¶

These should be generated dynamically:

1. API Reference
2. Generate from FastAPI OpenAPI spec
3. Include request/response examples from Pydantic schemas
4. Show authentication requirements

5. Link to related code

6. Module Documentation

7. Generate from Python docstrings using mkdocstrings
8. Include class hierarchy
9. Show method signatures with type hints

10. Link to source code on GitHub

11. Database Reference

12. Generate from SQLAlchemy models
13. Show table relationships (ER diagram)
14. Document columns, indexes, constraints

15. Migration history

16. Configuration Reference

17. Generate from Pydantic Settings models
18. Show all environment variables
19. Include types, defaults, validation rules

20. Security recommendations

21. Type Reference

22. Generate from Pydantic models and type hints
23. Show data structures
24. Include validation rules
25. JSON schema examples

📚 Archive (Keep for Reference)¶

Move to docs/archive/ or separate repository:

1. Implementation Reports (51 files, 23,713 lines)
2. These are historical implementation notes
3. Valuable for context but not user-facing
4. Keep in .claude/REPORTS/ for Claude Code context
5. Create index page in docs archive

Recommended Technology Stack¶

Core: MkDocs Material¶

MkDocs Material: Industry-standard documentation framework with: - Clean, responsive design (Shadcn-inspired available via custom CSS) - Built-in search - Dark/light theme - Mobile-friendly - Easy deployment (GitHub Pages, Netlify, Vercel)

pip install mkdocs-material

Auto-Generation Plugins¶

1. mkdocstrings-python - Generate docs from Python docstrings

   pip install mkdocstrings[python]
   

2. Extracts docstrings from Python modules
3. Shows type hints, signatures
4. Links to source code

5. Supports Google, NumPy, Sphinx docstring styles

6. mkdocs-swagger-ui-tag - Embed OpenAPI/Swagger UI

   pip install mkdocs-swagger-ui-tag
   

7. Embeds interactive API docs
8. Uses existing FastAPI OpenAPI spec

9. Try API endpoints directly from docs

10. mkdocs-mermaid2-plugin - Diagrams from code

    pip install mkdocs-mermaid2-plugin
    

11. Architecture diagrams
12. Sequence diagrams

13. ER diagrams for database

14. mkdocs-git-revision-date-localized-plugin - Show last updated dates

    pip install mkdocs-git-revision-date-localized-plugin
    

15. mkdocs-macros-plugin - Dynamic content generation

    pip install mkdocs-macros-plugin
    

16. Generate tables from config
17. Include environment variables
18. Reusable content blocks

Optional Enhancements¶

1. mkdocs-awesome-pages-plugin - Automatic navigation
2. mkdocs-minify-plugin - Optimize build size
3. mkdocs-redirects - Handle moved pages
4. pymdown-extensions - Enhanced markdown (admonitions, tabs, etc.)

Proposed Documentation Structure¶

docs/
├── index.md                          # Landing page (from README.md)
├── getting-started/
│   ├── index.md                      # Quick start
│   ├── installation.md               # Installation guide
│   ├── configuration.md              # Basic configuration
│   └── first-presentation.md         # Tutorial
│
├── user-guide/
│   ├── index.md                      # Overview
│   ├── user-management.md            # Managing users (consolidated)
│   ├── n8n-integration.md            # N8N workflows (consolidated)
│   ├── whitelabel.md                 # Branding guide (consolidated)
│   └── presentations.md              # Creating presentations
│
├── developer-guide/
│   ├── index.md                      # Developer overview
│   ├── architecture.md               # System architecture
│   ├── development-setup.md          # Local setup
│   ├── testing.md                    # Testing guide (consolidated)
│   ├── contributing.md               # Contribution guidelines
│   └── deployment.md                 # Deployment guide (consolidated)
│
├── api-reference/
│   ├── index.md                      # API overview
│   ├── openapi.md                    # 🤖 Embedded Swagger UI
│   ├── authentication.md             # Auth methods
│   └── examples.md                   # API usage examples
│
├── code-reference/                   # 🤖 Auto-generated
│   ├── index.md                      # Code overview
│   ├── ai/                           # AI provider modules
│   │   ├── index.md                  # 🤖 app.ai module docs
│   │   ├── lib.md                    # 🤖 Main AI interface
│   │   └── providers/                # 🤖 Provider implementations
│   ├── workflowengine/               # Workflow engine modules
│   ├── context/                      # RAG/vector search
│   ├── filemanager/                  # Storage backends
│   ├── auth/                         # Authentication
│   └── api/                          # API routers
│
├── database/
│   ├── index.md                      # Database overview
│   ├── schema.md                     # 🤖 Schema reference (from SQLAlchemy)
│   ├── migrations.md                 # Migration guide
│   └── er-diagram.md                 # 🤖 ER diagram (Mermaid)
│
├── configuration/
│   ├── index.md                      # Configuration overview
│   ├── environment-variables.md      # 🤖 Generated from Pydantic
│   ├── docker.md                     # Docker configuration
│   └── azure.md                      # Azure deployment config
│
├── operations/
│   ├── index.md                      # Operations overview
│   ├── monitoring.md                 # Health checks, metrics
│   ├── troubleshooting.md            # Common issues
│   └── production-checklist.md       # Pre-deployment checklist
│
├── project/
│   ├── roadmap.md                    # Feature roadmap
│   ├── changelog.md                  # 🤖 Generated from git
│   └── contributing.md               # How to contribute
│
└── archive/
    ├── index.md                      # Archive overview
    └── reports/                      # Historical implementation reports
        └── index.md                  # Report index (links to .claude/REPORTS/)

mkdocs.yml                            # MkDocs configuration
docs/stylesheets/custom.css           # Shadcn-inspired styling
docs/javascripts/custom.js            # Custom interactions
requirements-docs.txt                 # Documentation dependencies

Legend: - 🤖 = Auto-generated from source code - Plain = Handwritten markdown (consolidated from existing docs)

Implementation Plan¶

Phase 1: Foundation (2-3 days)¶

Goal: Set up MkDocs infrastructure and core documentation

1.1 Setup MkDocs (4 hours)¶

• Create docs/ directory structure
• Install MkDocs Material and plugins
• Create mkdocs.yml configuration
• Set up Material theme with custom styling (Shadcn-inspired)
• Configure search, navigation, theme settings

Deliverable: mkdocs serve runs and shows empty docs site

1.2 Create Core Pages (8 hours)¶

• index.md - Landing page (adapt from README.md)
• getting-started/installation.md - Quick start guide
• getting-started/configuration.md - Basic config
• developer-guide/architecture.md - System architecture
• developer-guide/development-setup.md - Local setup

Deliverable: Basic navigation and 5 core pages

1.3 Configure Auto-Generation (4 hours)¶

• Install mkdocstrings-python plugin
• Configure Python docstring rendering
• Test module documentation generation
• Set up source code linking (GitHub)

Deliverable: Working auto-generation for Python modules

Phase 2: Auto-Generated Documentation (3-4 days)¶

Goal: Generate API, module, and database documentation from code

2.1 API Documentation (6 hours)¶

• Install mkdocs-swagger-ui-tag plugin
• Embed FastAPI OpenAPI spec (/openapi.json)
• Create interactive API explorer
• Add authentication guide
• Add API usage examples

Deliverable: Interactive API documentation at /api-reference/

2.2 Module Documentation (8 hours)¶

• Set up mkdocstrings for all modules
• Generate docs for app.ai module
• Generate docs for app.workflowengine module
• Generate docs for app.context module
• Generate docs for app.filemanager module
• Generate docs for app.auth module
• Generate docs for app.api module
• Add navigation structure for code reference

Deliverable: Complete code reference section

2.3 Database Documentation (4 hours)¶

• Create script to extract SQLAlchemy schema
• Generate ER diagram using Mermaid
• Document all tables, columns, relationships
• Link to migration files

Deliverable: Database reference section

2.4 Configuration Documentation (2 hours)¶

• Create script to extract Pydantic Settings
• Generate environment variable reference
• Add descriptions from Field() metadata
• Add security notes for sensitive variables

Deliverable: Configuration reference section

Phase 3: Consolidate Existing Docs (2-3 days)¶

Goal: Migrate and consolidate .claude docs into new structure

3.1 User Guides (6 hours)¶

• Consolidate USER_MANAGEMENT.md (1,240 → ~600 lines)
• Remove redundant examples
• Keep essential CLI commands
• Link to auto-generated API docs
• Consolidate N8N_INTEGRATION.md (579 → ~400 lines)
• Focus on integration patterns
• Remove repetitive setup steps
• Consolidate BRANDING.md (384 → ~300 lines)
• Merge with WHITELABEL_QUICKSTART.md
• Create single branding guide

Deliverable: 3 consolidated user guides

3.2 Developer Guides (6 hours)¶

• Create testing.md (from TESTING_GUIDE.md, 445 → ~300 lines)
• Create deployment.md (from DEPLOYMENT_CHECKLIST.md, 547 → ~400 lines)
• Create contributing.md (new, ~200 lines)
• Update CLAUDE.md to reference new docs

Deliverable: 3 developer guides

3.3 Operations Guides (4 hours)¶

• Create troubleshooting.md (new, ~200 lines)
• Create production-checklist.md (consolidated, ~200 lines)
• Create monitoring.md (new, ~150 lines)

Deliverable: 3 operations guides

Phase 4: Improve Source Code Documentation (3-5 days)¶

Goal: Fill gaps in docstring coverage for better auto-generation

4.1 Critical Modules (Priority 1) (8 hours)¶

• context/ module (9.1% → 80% file docs)
• Add module docstrings
• Document key functions (chunking, embedding, retrieval)
• Add usage examples
• auth/ module (15% → 80% class docs)
• Document session management
• Document Azure AD integration
• Add authentication flow examples

Deliverable: Context and Auth modules well-documented

4.2 Core Application (Priority 2) (6 hours)¶

• main.py (31% → 80% coverage)
• Document startup sequence
• Document middleware
• Document error handlers
• celery_app.py (0% → 80% coverage)
• Document task configuration
• Document worker setup

Deliverable: Core app files documented

4.3 Utility Modules (Priority 3) (6 hours)¶

• util/ module (26% → 70% file docs)
• Add file-level docstrings to 23 utility files
• Document key utility functions
• Add usage examples

Deliverable: Utility modules documented

Phase 5: Polish & Deploy (1-2 days)¶

Goal: Finalize docs site and set up deployment

5.1 Visual Polish (4 hours)¶

• Create custom CSS for Shadcn-inspired theme
• Modern color scheme
• Clean typography
• Consistent spacing
• Add diagrams using Mermaid
• Architecture overview
• Workflow execution flow
• Authentication flow
• Add screenshots to user guides
• Optimize images and assets

Deliverable: Polished visual design

5.2 CI/CD Integration (4 hours)¶

• Create .github/workflows/docs.yml
• Build docs on every commit
• Deploy to GitHub Pages (or Vercel)
• Run on PRs to preview changes
• Add build script: docs/build_docs.sh
• Add Docker build: docs/Dockerfile.docs

Deliverable: Automated docs deployment

5.3 Final Review (4 hours)¶

• Test all links (internal and external)
• Check all auto-generated content
• Verify search functionality
• Test mobile responsiveness
• Review for consistency and clarity

Deliverable: Production-ready documentation site

Phase 6: Maintenance & Archive (1 day)¶

Goal: Set up long-term maintenance strategy

6.1 Archive Implementation Reports (2 hours)¶

• Create docs/archive/reports/index.md
• Generate index of all 51 reports with summaries
• Keep original files in .claude/REPORTS/ for Claude context
• Link from docs archive to GitHub tree view

Deliverable: Searchable archive of implementation reports

6.2 Documentation Guidelines (2 hours)¶

• Create docs/project/documentation-guidelines.md
• When to add docstrings
• How to write good docstrings
• When to create markdown guides
• How to update docs
• Add pre-commit hook to check docstring coverage

Deliverable: Guidelines for maintaining docs

6.3 Update CLAUDE.md (2 hours)¶

• Update CLAUDE.md to reference new docs structure
• Update "Common Commands" section
• Add docs build commands
• Link to documentation guidelines

Deliverable: Updated developer guide

Effort Estimate¶

Recommended Approach: Incremental rollout 1. Start with Phase 1-2 (auto-generation) - provides immediate value 2. Phase 3 (consolidation) - can be done in parallel 3. Phase 4 (source code docs) - ongoing improvement 4. Phase 5-6 (polish) - when ready to launch publicly

Success Metrics¶

Quantitative¶

• ✅ Reduce handwritten docs: 28,000 → 2,100 lines (93% reduction)
• ✅ Auto-generate: API docs, module docs, database schema, config reference
• ✅ Docstring coverage: 80%+ for all modules
• ✅ Build time: < 60 seconds
• ✅ Search results: < 100ms
• ✅ Page load: < 2 seconds

Qualitative¶

• ✅ Developers can find API docs in < 30 seconds
• ✅ New users can get started in < 10 minutes
• ✅ Docs stay up-to-date with code changes (auto-generation)
• ✅ Single source of truth (no duplicate docs)
• ✅ Mobile-friendly and accessible

Technology Stack Summary¶

Required Dependencies¶

Add to requirements-docs.txt:

mkdocs>=1.5.0
mkdocs-material>=9.4.0
mkdocstrings[python]>=0.24.0
mkdocs-swagger-ui-tag>=0.6.0
mkdocs-mermaid2-plugin>=1.1.0
mkdocs-git-revision-date-localized-plugin>=1.2.0
mkdocs-macros-plugin>=1.0.0
pymdown-extensions>=10.0.0

MkDocs Configuration¶

Key settings in mkdocs.yml:

site_name: S5 Slidefactory Documentation
site_url: https://docs.slidefactory.io
repo_url: https://github.com/your-org/s5-slidefactory
repo_name: s5-slidefactory

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: [app]
          options:
            docstring_style: google
            show_source: true
            show_root_heading: true
            show_root_toc_entry: true
            heading_level: 2
  - swagger-ui-tag
  - mermaid2
  - git-revision-date-localized:
      enable_creation_date: true
  - macros

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - attr_list
  - md_in_html
  - tables
  - footnotes
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

extra_css:
  - stylesheets/custom.css

extra_javascript:
  - javascripts/custom.js

Risks & Mitigations¶

Risk 1: Docstring Coverage Too Low¶

Impact: Auto-generated docs will be sparse Mitigation: Phase 4 focuses on improving docstrings before launch

Risk 2: Build Time Too Long¶

Impact: Slow CI/CD pipeline Mitigation: Use incremental builds, cache dependencies, split large modules

Risk 3: Migration Effort Underestimated¶

Impact: Takes longer than 2-3 weeks Mitigation: Prioritize critical sections (Phases 1-2), defer polish (Phase 5)

Risk 4: Docs Become Stale¶

Impact: Out-of-date documentation Mitigation: Auto-generation reduces staleness, add "last updated" dates, CI checks

Risk 5: Theme Customization Complexity¶

Impact: Custom CSS/JS takes longer than expected Mitigation: Start with default Material theme, iterate on customization

Next Steps¶

Immediate Actions (This Week)¶

1. Get approval for this plan from stakeholders
2. Create docs/ directory and set up MkDocs Material
3. Install plugins and create basic configuration
4. Create landing page from README.md
5. Test auto-generation with one module (e.g., app.ai)

Week 2-3¶

1. Complete Phase 1 (Foundation)
2. Complete Phase 2 (Auto-generation)
3. Start Phase 3 (Consolidation)

Week 4+¶

1. Complete Phase 3-4 (Consolidation + Source code docs)
2. Polish and deploy (Phase 5)
3. Set up maintenance (Phase 6)

Appendix A: Example Auto-Generated Content¶

Example 1: Module Documentation (from docstring)¶

Source Code (app/ai/lib.py):

"""AI provider abstraction layer.

This module provides a unified interface for working with multiple
AI providers (OpenAI, Azure OpenAI, Mistral, Anthropic, etc.).

Example:
    Generate text with automatic provider selection:

    >>> from app.ai.lib import generate_text
    >>> result = await generate_text(
    ...     prompt="Write a haiku about Python",
    ...     model="gpt-4"
    ... )
    >>> print(result)
"""

async def generate_text(
    prompt: str,
    model: str,
    provider: Optional[str] = None,
    temperature: float = 0.7,
    max_tokens: int = 1000
) -> str:
    """Generate text using the specified AI model.

    Args:
        prompt: The input prompt to send to the model
        model: Model name (e.g., "gpt-4", "claude-3-sonnet")
        provider: Optional provider name (auto-detected if omitted)
        temperature: Sampling temperature (0.0 to 1.0)
        max_tokens: Maximum tokens to generate

    Returns:
        Generated text response

    Raises:
        ProviderNotFoundError: If provider is not configured
        ModelNotFoundError: If model is not available
        GenerationError: If generation fails

    Example:
        >>> result = await generate_text(
        ...     prompt="Explain FastAPI",
        ...     model="gpt-4",
        ...     temperature=0.5
        ... )
    """

Auto-Generated Docs (via mkdocstrings): ![Module docs with signature, parameters, return type, examples]

Example 2: API Documentation (from OpenAPI)¶

Source Code (app/api/presentations.py):

@router.post("/generate", response_model=PresentationResponse)
async def generate_presentation(
    request: PresentationRequest,
    current_user: User = Depends(get_current_user)
):
    """Generate a PowerPoint presentation.

    This endpoint accepts a template ID and data (JSON or result ID)
    and generates a PowerPoint presentation asynchronously.

    **Authentication**: Required (session-based)

    **Rate Limit**: 10 requests per minute per user
    """

Auto-Generated Docs (via Swagger UI): ![Interactive API explorer with request/response examples, try it out button]

Example 3: Database Schema (from SQLAlchemy)¶

Source Code (app/models/template.py):

class Template(Base):
    """PowerPoint template model.

    Stores template metadata and file references for presentation
    generation.

    Relationships:
        - tags: Many-to-many relationship with Tag model
        - presentations: One-to-many with Presentation model
    """
    __tablename__ = "templates"

    id = Column(Integer, primary_key=True)
    name = Column(String(255), nullable=False)
    description = Column(Text)
    file_path = Column(String(500), nullable=False)
    created_at = Column(DateTime, default=func.now())

    tags = relationship("Tag", secondary=template_tags, back_populates="templates")

Auto-Generated Docs (via custom script + Mermaid):

erDiagram
    TEMPLATE ||--o{ PRESENTATION : generates
    TEMPLATE }o--o{ TAG : has
    TEMPLATE {
        int id PK
        string name
        text description
        string file_path
        datetime created_at
    }

Appendix B: Shadcn-Inspired Custom CSS¶

/* docs/stylesheets/custom.css */

:root {
  --md-primary-fg-color: #6366f1;        /* Indigo */
  --md-accent-fg-color: #8b5cf6;         /* Purple */
  --md-default-bg-color: #ffffff;
  --md-default-fg-color: #0f172a;        /* Slate 900 */
  --md-code-bg-color: #f1f5f9;           /* Slate 100 */
  --md-code-fg-color: #334155;           /* Slate 700 */

  /* Shadcn-inspired spacing */
  --md-spacing-unit: 0.25rem;

  /* Border radius */
  --md-border-radius: 0.5rem;
}

/* Dark mode */
[data-md-color-scheme="slate"] {
  --md-default-bg-color: #0f172a;        /* Slate 900 */
  --md-default-fg-color: #f1f5f9;        /* Slate 100 */
  --md-code-bg-color: #1e293b;           /* Slate 800 */
  --md-code-fg-color: #cbd5e1;           /* Slate 300 */
}

/* Modern card style for admonitions */
.md-typeset .admonition {
  border-radius: var(--md-border-radius);
  box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
}

/* Code blocks */
.md-typeset pre > code {
  border-radius: var(--md-border-radius);
}

/* Tables */
.md-typeset table:not([class]) {
  border-radius: var(--md-border-radius);
  overflow: hidden;
}

/* Buttons */
.md-button {
  border-radius: var(--md-border-radius);
  transition: all 0.2s ease;
}

.md-button:hover {
  transform: translateY(-1px);
  box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
}

Appendix C: Build Script¶

#!/bin/bash
# docs/build_docs.sh

set -e

echo "📚 S5 Slidefactory Documentation Builder"
echo "========================================"

# Check for virtual environment
if [ ! -d "venv-docs" ]; then
    echo "Creating virtual environment..."
    python3 -m venv venv-docs
fi

# Activate virtual environment
source venv-docs/bin/activate

# Install dependencies
echo "Installing dependencies..."
pip install -r requirements-docs.txt

# Build or serve based on argument
if [ "$1" == "build" ]; then
    echo "Building static site..."
    mkdocs build --clean --strict
    echo "✅ Build complete! Output in site/"
elif [ "$1" == "deploy" ]; then
    echo "Deploying to GitHub Pages..."
    mkdocs gh-deploy --force
    echo "✅ Deployed!"
else
    echo "Serving documentation..."
    echo "📖 Open http://127.0.0.1:8000 in your browser"
    mkdocs serve
fi

Conclusion¶

This plan creates a sustainable, living documentation system that:

✅ Reduces maintenance burden by auto-generating from source code ✅ Stays up-to-date automatically as code changes ✅ Provides single source of truth in the codebase ✅ Consolidates 28,000 lines into ~2,100 lines of essential guides ✅ Leverages existing docstrings and FastAPI OpenAPI ✅ Uses modern tooling (MkDocs Material, mkdocstrings) ✅ Deploys automatically via CI/CD

The key principle: Documentation lives in the code, rendered in a beautiful UI.

Next Step: Review this plan and get approval to proceed with Phase 1.