epic: VitePress Documentation Site with Scientific Visualization Suite

[Anselmoo]

VitePress Documentation Site with Scientific Visualization Suite

🎯 Epic Summary

Create a modern documentation site using VitePress with Catppuccin Mocha theme, featuring state-of-the-art scientific visualization for optimizer benchmark results inspired by COCO/IOHprofiler standards.

This is the parent epic tracking all documentation work. See sub-issues below for implementation details.

---

📊 Sub-Issue Tracking Table

🚀 Phase 1: Foundation ✅ COMPLETE

#	Issue	Description	Status
1	#83	VitePress Foundation Setup	✅ Done
2	#65	COCO/BBOB Docstring Template	✅ Done

📐 Phase 2: Base Classes & Automation ✅ COMPLETE

#	Issue	Description	Status
3	#66	Update Abstract Base Classes	✅ Done
4	#67	Batch Docstring Script	✅ Done
5	#79	Pre-commit Hooks	✅ Done

📝 Phase 3: Docstring Updates (~80% Complete)

#	Issue	Description	Status
6	#68	Validation Checkpoints (10 files)	🔄 In Progress
7	#69	Classical Category (9 files)	🔄 In Progress
8	#70	Swarm Intelligence (56 files)	🔄 In Progress
9	#71	Gradient-Based (11 files)	✅ Done
10	#72	Evolutionary (6 files)	✅ Done
11	#73	Metaheuristic (14 files)	🔄 In Progress
12	#74	Physics-Inspired (4 files)	🔄 In Progress
13	#75	Probabilistic (5 files)	🔄 In Progress
14	#76	Social-Inspired (4 files)	🔄 In Progress
15	#77	Constrained (5 files)	✅ Done
16	#78	Multi-Objective (3 files)	🔄 In Progress

📊 Phase 4: Visualization & Data Pipeline 🚧 ACTIVE

#	Issue	Description	Status
17	#84	ECharts Vue Components (ECDF, Convergence, Violin, 3D)	🔄 PR #120
18	#85	Benchmark Data Collection (COCO/BBOB spec)	🔄 PR #119 foundation
19	#127	🆕 Benchmark Data Pipeline: CI → Extract → Artifact	🆕 New
20	#110	Schema-Driven Documentation (Pydantic)	🔄 In Progress

🔧 Phase 5: Integration & Documentation

#	Issue	Description	Status
21	#80	Documentation Generator (Griffe → VitePress)	🔄 In Progress
22	#81	ECharts Architecture Docs	🔄 Open
23	#126	Phase 4/5: COCO-compliant doctests + NumPy 2.x fixes	🆕 New

🚀 Phase 6: Deployment

#	Issue	Description	Status
24	#86	CI/CD & GitHub Pages	⏳ Waiting

---

🔀 Dependency Flow Diagram (January 2026)

flowchart TB
    subgraph PHASE1["✅ PHASE 1-3: COMPLETE"]
        direction LR
        p65["#65 COCO Template ✅"]
        p66["#66 Abstract Base ✅"]
        p67["#67 Batch Script ✅"]
        p79["#79 Pre-commit ✅"]
        p83["#83 VitePress ✅"]
        docs(["113 Optimizers ✅"])
        
        p65 --> p66 --> p67 --> p79
        p65 -.-> docs
        p83 -.-> docs
    end

    subgraph PHASE4["🚧 PHASE 4: ACTIVE"]
        pr119["PR #119 History ✅ MERGED"]
        pr120["PR #120 Charts ✅ MERGED"]
        
        subgraph NEXT["[P] ASSIGN NOW"]
            i126{{"#126 NumPy 2.x 🚨"}}
            i127{{"#127 Pipeline"}}
        end
        
        i110["#110 Schema"]
    end

    subgraph PHASE5["⏳ PHASE 5-6: WAITING"]
        subgraph LATER["[P] PARALLEL"]
            i80["#80 Doc Gen"]
            i81["#81 Arch Docs"]
        end
        i86["#86 Deploy"]
    end

    docs --> pr119 --> pr120
    pr119 -->|"[P]"| i126
    pr119 -->|"[P]"| i127
    i126 --> i110
    i127 --> i110
    i110 -->|"[P]"| i80
    i110 -->|"[P]"| i81
    i80 --> i86
    i81 --> i86

    classDef done fill:#a6e3a1,stroke:#40a02b
    classDef blocker fill:#f38ba8,stroke:#d20f39
    classDef active fill:#fab387,stroke:#fe640b
    classDef waiting fill:#cdd6f4,stroke:#6c7086

    class p65,p66,p67,p79,p83,docs,pr119,pr120 done
    class i126 blocker
    class i127,i110 active
    class i80,i81,i86 waiting

Loading

---

🚨 Current Blockers (January 2026)

Blocker	Issue	Impact	Resolution
NumPy 2.x np.True_	#126 Task 0	110/113 doctests fail	Wrap assertions in bool()
No benchmark pipeline	#127	PR #120 uses mock data only	CI workflow + aggregation script
No early stopping	#127 Phase 1	Wastes compute, unfair comparison	Add _check_convergence() method
No n_evaluations	#127 Phase 1	Can't compute ERT metric	Track function evaluation count

---

🎯 Success Criteria

Metric	Target	Current
Documentation Coverage	All 120+ algorithms	~80% (113 updated)
Visualization Quality	Research-grade charts	🔄 Mock data only
Lighthouse Score	> 90 on all metrics	⏳ Not deployed
Accessibility	WCAG AA compliance	⏳ Pending
Search Performance	Sub-100ms via Pagefind	⏳ Pending
Build Time	< 60 seconds full site	⏳ Pending

---

🛠️ Technology Stack

Component	Technology	Status
SSG	VitePress 1.6.4	✅ Configured
Theme	Catppuccin Mocha	✅ Applied
2D Charts	ECharts + vue-echarts	🔄 PR #120
3D Viz	TresJS (Three.js wrapper)	🔄 PR #120
Search	Pagefind	⏳ Pending
Math	MathJax	✅ Working
API Docs	Griffe → JSON	🔄 In Progress
CI/CD	GitHub Actions + Pages	⏳ Pending
Data Validation	Pydantic + JSON Schema	🔄 #110

---

📋 All Sub-Issues (Organized by Status)

✅ Completed

• Create COCO/BBOB Docstring Template #65 - COCO/BBOB Docstring Template
• Update Abstract Base Classes with COCO/BBOB Requirements #66 - Update Abstract Base Classes
• Create Batch Docstring Update Script #67 - Batch Docstring Script
• Update Optimizer Docstrings - Gradient-Based Category (11 files) #71 - Gradient-Based (11 files)
• Update Optimizer Docstrings - Evolutionary Category (6 files) #72 - Evolutionary (6 files)
• Update Optimizer Docstrings - Constrained Category (5 files) #77 - Constrained (5 files)
• Add Pre-commit Hooks for Optimizer Docstring Validation #79 - Pre-commit Hooks
• Initialize VitePress Foundation with Catppuccin Theme #83 - VitePress Foundation
• docs: investigate and migrate away from legacy doc dependencies (markdown-it-mathjax3, legacy wrappers) — evaluate ECharts & Math renderer alternatives #96 - Additional cleanup

🔄 In Progress

• CI/Documentation Quality: Pre-commit Failures & Ruff Exception Reduction #68 - Validation Checkpoints
• Update Optimizer Docstrings - Classical Category (9 files) #69 - Classical (9 files)
• Update Optimizer Docstrings - Swarm Intelligence Category (56 files) #70 - Swarm Intelligence (56 files)
• Update Optimizer Docstrings - Metaheuristic Category (14 files) #73 - Metaheuristic (14 files)
• Update Optimizer Docstrings - Physics-Inspired Category (4 files) #74 - Physics-Inspired (4 files)
• Update Optimizer Docstrings - Probabilistic Category (5 files) #75 - Probabilistic (5 files)
• Update Optimizer Docstrings - Social-Inspired Category (4 files) #76 - Social-Inspired (4 files)
• Update Optimizer Docstrings - Multi-Objective Category (3 files) #78 - Multi-Objective (3 files)
• Restore Documentation Generator with Griffe + AST Extraction #80 - Documentation Generator
• Document ECharts Architecture Decision and Fix SSR Issues #81 - ECharts Architecture Docs
• ECharts Vue Components for Scientific Visualization + Schema Integration #84 - ECharts Vue Components (PR Replace deprecated ECharts-GL with TresJS, fix SSR build errors, and add mock benchmark data #120)
• COCO/BBOB Benchmark Data Collection Suite + History Tracking Implementation #85 - Benchmark Data Collection
• Schema-Driven Documentation: Pydantic Models + Automated CI/Hook Enforcement #110 - Schema-Driven Documentation

🆕 New (Added January 2026)

• Phase 4/5: Replace trivial doctests with COCO-compliant benchmarks (Tasks 2&3 parallel) #126 - Phase 4/5: COCO-compliant doctests + NumPy 2.x fixes
• COCO/BBOB Benchmark Data Pipeline: CI → Extract → Artifact Storage #127 - Benchmark Data Pipeline: CI → Extract → Artifact Storage

⏳ Waiting

• Setup CI/CD Pipeline for GitHub Pages Deployment #86 - CI/CD & GitHub Pages

---

📚 References

• COCO Platform - Comparing Continuous Optimizers
• IOHprofiler - Optimization Heuristics Profiler
• VitePress - Vue-powered SSG
• ECharts - Visualization library
• TresJS - Vue + Three.js for 3D
• Catppuccin - Theme

---

📋 Related PRs

• PR Add COCO/BBOB benchmark infrastructure with memory-efficient history tracking #119 - History tracking infrastructure (✅ MERGED)
• PR Replace deprecated ECharts-GL with TresJS, fix SSR build errors, and add mock benchmark data #120 - ECharts Vue components + TresJS (🔄 READY TO MERGE)

📋 Related Issues

• docs: MkDocs Material Documentation with Built-in Color Palette & Scientific Visualization #54 - MkDocs Material alternative
• docs: Zensical Documentation Site with Scientific Visualization Suite #55 - Zensical alternative
• Reduce Ruff ignore list and tighten lint scope #82 - Ruff linting cleanup