Unified API Documentation Navigation

[reluctantfuturist]

RFC: Unified API Documentation Navigation

Problems

1. Overall documentation structure is still not as clear as it can be.
2. The API reference is monolithic and is extremely hard to navigate.
3. We have two documentation renderers -- Sphinx for the main docs and Stoplight Elements for the API -- which is a clunky UX.

Proposal

#3407 introduces a horizontal nav bar that lets users switch between main docs and API reference. Building on this, the proposal is to:

• Separate content accordingly: keep information on core concepts, guides, how-tos and tools in the Docs tab, and move all API-related content to the API tab.
• Split monolithic API reference into individual Sphinx pages per API category, each embedding targeted Stoplight Elements views.

Implementation

1. Navigation Structure Redesign

docs/source/ 
├── api-reference/ 
│   ├── index.md              # API overview 
│   ├── inference.md          # Inference API only 
│   ├── telemetry.md             # Telemetry API only   
│   ├── safety.md             # Safety API only 
│   ├── vector_stores.md             # Vector stores API only 
│   └── [other-apis].md

2. Generator Enhancement

Modify **generate.py**:

• Generate filtered OpenAPI specs per API category
• Output individual JSON specs: inference-spec.json, agents-spec.json, etc.
• Keep full spec for legacy compatibility

3. Sphinx Integration

Each API page template:

<elements-api layout="stacked" hideTryIt="false"></elements-api> 
<script> 
document.querySelector('elements-api').apiDescriptionDocument =      {{ api_category_spec_json }}; 
</script>

4. Navigation Updates

Current: Single "API Reference" → Full spec embed
New: "API Reference" parent with:

• Overview
• Inference
• Telemetry
• Safety
• Vector stores
• [etc.]