website-htmx-rustelo-code/site/templates/build-tools/documentation/automation.tera

{% extends "documentation/base.tera" %}

{% block title %}{{ i18n.labels.title_automation }}{% endblock title %}

{% block toc %}
## {{ i18n.labels.table_of_contents }}

- [{{ i18n.labels.overview }}](#overview)
- [Rustelo Manager Integration](#rustelo-manager)
- [MCP Server Integration](#mcp-server)
- [API Client Generation](#api-client)
- [Testing Automation](#testing)
- [Documentation Generation](#docs-generation)
- [CI/CD Integration](#ci-cd)

{% endblock toc %}

{% block content %}

## {{ i18n.labels.overview }} {% raw %}{#overview}{% endraw %}

The Rustelo route documentation system generates comprehensive metadata that powers numerous automation scenarios beyond basic API client generation. This system is designed to be the single source of truth for all routing, component, and page information in your application.

## 🚀 Automation Possibilities

### 1. Rustelo Manager Integration {% raw %}{#rustelo-manager}{% endraw %}

The generated documentation directly powers the **Rustelo Manager** dashboard:

- **Route Discovery**: Automatically populates available routes for navigation
- **Component Inspector**: Live component documentation and prop validation  
- **Page Editor**: Dynamic form generation based on page route configurations
- **Feature Detection**: Shows which features are enabled for each route

```rust
// Example: Manager uses generated data for route management
let routes = load_route_data("site/info/server/data.toml");
manager.populate_routes(routes);
```

### 2. MCP Server Integration {% raw %}{#mcp-server}{% endraw %}

Transform your Rustelo app into an **MCP (Model Context Protocol) Server**:

- **Route Endpoints**: Expose API routes as MCP tools
- **Component Library**: Share component definitions with AI assistants
- **Page Templates**: Generate new pages using existing patterns
- **Real-time Updates**: Live documentation updates via MCP

```rust
// Example: MCP tool for route information
#[mcp_tool]
fn get_route_info(path: &str) -> Result<RouteInfo, McpError> {
    let routes = load_generated_routes()?;
    routes.find_by_path(path).ok_or_else(|| McpError::NotFound)
}
```

### 3. API Client Generation {% raw %}{#api-client}{% endraw %}

Generate type-safe API clients from route documentation:

{% if doc.routes %}
**Available Routes for Client Generation:**

{% for route in doc.routes %}
{% if route.methods %}
- `{{ route.path }}` - {{ route.handler }}
{% endif %}
{% endfor %}
{% endif %}

```typescript
// Generated TypeScript client
export class RusteloApiClient {
{% for route in doc.routes %}
{% if route.methods %}
  async {{ route.handler }}(): Promise<{{ route.response_type }}> {
    return this.request('{{ route.path }}', 'GET');
  }
{% endif %}
{% endfor %}
}
```

### 4. Testing Automation {% raw %}{#testing}{% endraw %}

Automated test generation from route specifications:

```rust
// Generated integration tests
{% for route in doc.routes %}
{% if route %}
#[tokio::test]
async fn test_route_{{ loop.index }}() {
    let app = create_test_app().await;
    let response = app
        .oneshot(Request::builder()
            .uri("{{ route.path }}")
            .method("{{ route.methods | first }}")
            .body(Body::empty())?)
        .await?;
    
    assert_eq!(response.status(), StatusCode::OK);
}
{% endif %}
{% endfor %}
```

### 5. Documentation Generation {% raw %}{#docs-generation}{% endraw %}

Multi-format documentation from the same source:

- **OpenAPI/Swagger**: Auto-generated API specs
- **Markdown**: Human-readable documentation (this file!)
- **JSON Schema**: Machine-readable specifications
- **Postman Collections**: Ready-to-use API collections

### 6. CI/CD Integration {% raw %}{#ci-cd}{% endraw %}

Automate deployment and validation:

```yaml
# GitHub Actions integration
- name: Validate Route Documentation
  run: |
    cargo run --bin site-info-validator
    
- name: Generate API Documentation
  run: |
    cargo run --bin docs-generator --format openapi
    
- name: Update Postman Collection
  run: |
    cargo run --bin postman-generator
```

## 📊 Current System Statistics

Based on the current route analysis:

- **{{ summary.total_routes }}** total routes available for automation
- **{{ summary.api_routes }}** API routes for client generation
- **{{ summary.static_routes }}** static routes for optimization
- **{{ summary.total_components }}** components for template generation
- **{{ summary.total_pages }}** pages across **{{ summary.languages | length }}** languages

## 🔧 Integration Examples

### Route Validation Pipeline

```rust
use site_info::route_analysis::RouteDocumentation;

// Validate all routes are documented
fn validate_documentation_completeness() -> Result<(), ValidationError> {
    let docs = RouteDocumentation::load_from_analysis()?;
    
    // Check all routes have descriptions
    for route in &docs.api_routes {
        if route.description.is_none() {
            eprintln!("Warning: Route {} lacks description", route.path);
        }
    }
    
    // Validate auth requirements consistency
    validate_auth_consistency(&docs.api_routes)?;
    
    Ok(())
}
```

### Dynamic Menu Generation

```rust
// Generate navigation menus from page routes
fn generate_navigation_menu(language: &str) -> Result<NavMenu, MenuError> {
    let docs = RouteDocumentation::load_from_analysis()?;
    let pages = docs.page_routes
        .iter()
        .filter(|p| p.language == language && p.enabled)
        .collect();
        
    NavMenu::from_pages(pages)
}
```

This automation system transforms static route definitions into a powerful foundation for development tooling, testing, and deployment automation.

{% endblock content %}