Implement schema-to-VitePress integration: wire Griffe JSON API to Vue data loaders

[Copilot]

Griffe generates comprehensive JSON API files (docs/api/*.json), but VitePress data loaders and Vue components weren't consuming this schema. The JSON existed but wasn't wired to the frontend.

Implementation

Type System (docs/.vitepress/types/griffe.d.ts)

• TypeScript interfaces for Griffe's AST-style JSON output
• Handles ExprName, ExprSubscript, ExprTuple, ExprList annotation types

Data Loader (docs/.vitepress/loaders/api.data.ts)

• Navigates nested structure: opt.members.{category}.members.{submodule}.members.{Class}
• Converts Griffe's list-based parameters to component-friendly format
• Transforms annotations: ExprSubscript → "Callable[[ndarray], float]"
• Builds class index for 118 optimizers across 10 categories

Component Registration

• Registered APIDoc.vue in theme for algorithm pages

Usage

Algorithm pages can now auto-generate API documentation from Python source:

<script setup lang="ts">
import { data as apiData } from '../../.vitepress/loaders/api.data'
import APIDoc from '../../.vitepress/theme/components/APIDoc.vue'
import { computed } from 'vue'

const classDoc = computed(() => {
  const module = apiData.modules.swarm_intelligence
  return module?.classes?.find(c => c.name === 'ParticleSwarm')
})
</script>

<APIDoc v-if="classDoc" :classDoc="classDoc" />

Test Pages

• /api-data-test - Basic data loading verification
• /api-test/ - Full AntColony integration example
• /api-test/USAGE_GUIDE.md - Developer documentation with import path patterns

Data Coverage

All 10 optimizer categories loaded: swarm_intelligence (56), evolutionary (6), gradient_based (11), classical (9), metaheuristic (15), physics_inspired (4), probabilistic (5), social_inspired (4), constrained (5), multi_objective (3).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Schema-to-VitePress Integration: Connect JSON API to Vue Data Loaders</issue_title>
<issue_description>## 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</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Schema-to-VitePress Integration: Connect JSON API to Vue Data Loaders #133

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.