Schema-to-VitePress Integration: Connect JSON API to Vue Data Loaders

[Anselmoo]

Problem

PR #131 generates comprehensive JSON API files via Griffe (docs/api/*.json), but VitePress data loaders and Vue components don't yet consume this schema effectively. The JSON exists but isn't wired to the frontend.

Context

• Depends on: Restore Documentation Generator with Griffe + AST Extraction #80 (PR Add Griffe integration for JSON API documentation generation #131 - Griffe integration)
• Part of: epic: VitePress Documentation Site with Scientific Visualization Suite #52 (Documentation Epic)
• Related: Schema-Driven Documentation: Pydantic Models + Automated CI/Hook Enforcement #110 (Schema-Driven Documentation)

Current State

After PR #131 merges:

docs/api/
├── full_api.json        (~4MB, complete package)
├── swarm_intelligence.json
├── evolutionary.json
├── classical.json
└── ... (10 category files)

Gap Analysis

What Exists

• ✅ Griffe JSON output with type signatures, docstrings, methods
• ✅ docs/.vitepress/loaders/api.data.ts stub
• ✅ APIDoc.vue component scaffold
• ✅ optimizers.json metadata (135KB, 117 optimizers)

What's Missing

1. Data Loader Implementation - api.data.ts needs to transform Griffe JSON → typed interfaces
2. Component Binding - Vue components need props for algorithm pages
3. Type Definitions - TypeScript interfaces for Griffe output structure
4. Category Routing - Dynamic imports per algorithm category

Implementation

1. Type Definitions

Create docs/.vitepress/types/griffe.d.ts:

export interface GriffeClass {
  name: string
  docstring: { parsed: DocstringSection[] }
  members: GriffeMember[]
  bases: string[]
}

export interface GriffeMember {
  kind: 'function' | 'attribute'
  name: string
  signature: string
  docstring: { parsed: DocstringSection[] }
}

export interface DocstringSection {
  kind: 'text' | 'parameters' | 'returns' | 'examples'
  value: string | Parameter[]
}

2. Data Loader Enhancement

Update docs/.vitepress/loaders/api.data.ts:

import { defineLoader } from 'vitepress'
import type { GriffeClass } from '../types/griffe'

export default defineLoader({
  watch: ['../api/*.json'],
  async load(watchedFiles) {
    return watchedFiles.map(file => {
      const data = JSON.parse(fs.readFileSync(file, 'utf-8'))
      return transformGriffeToAPI(data)
    })
  }
})

3. Component Integration

Wire APIDoc.vue to consume loaded data:

<script setup lang="ts">
import { useData } from 'vitepress'
const { params } = useData()
const classDoc = computed(() => 
  apiData.value.find(c => c.name === params.optimizer)
)
</script>

Acceptance Criteria

• TypeScript interfaces match Griffe JSON structure
• Data loader transforms all 10 category JSON files
• APIDoc.vue renders parameter tables from real data
• Algorithm pages display docstring sections correctly
• No hardcoded mock data in Vue components
• VitePress build succeeds with data loaders

Validation

cd docs && npm run docs:build  # Build with real data
npm run docs:dev               # Dev server renders API pages

Complexity

Medium - TypeScript + Vue data flow

Labels

documentation, enhancement