generate_schema_docs.py

#!/usr/bin/env python3
"""
Generate Markdown documentation from YAML annotation schema.

This script reads c4-annotations-schema.yaml and generates
SCHEMA.md with formatted documentation for users.
"""

import yaml
from pathlib import Path


def generate_markdown(schema_path: Path, output_path: Path):
    """Generate Markdown documentation from YAML schema."""
    
    with open(schema_path, 'r') as f:
        schema = yaml.safe_load(f)
    
    lines = []
    
    # Warning header
    lines.append("<!-- ")
    lines.append("=" * 77)
    lines.append("⚠️  DO NOT EDIT THIS FILE DIRECTLY")
    lines.append("=" * 77)
    lines.append("")
    lines.append("This file is automatically generated from "
                 "c4-annotations-schema.yaml")
    lines.append("")
    lines.append("To make changes:")
    lines.append("1. Edit c4-annotations-schema.yaml")
    lines.append("2. Run: make docs (or python3 generate_schema_docs.py)")
    lines.append("3. Commit both files")
    lines.append("")
    lines.append("=" * 77)
    lines.append("-->")
    lines.append("")
    
    # Header
    lines.append("# C4 Annotation Schema Reference")
    lines.append("")
    lines.append(f"**Version:** {schema['schema_version']}")
    lines.append("")
    lines.append("This document describes all available C4 model "
                 "annotations for use in")
    lines.append("Python docstrings and comments.")
    lines.append("")
    lines.append("---")
    lines.append("")
    
    # Table of Contents
    lines.append("## Table of Contents")
    lines.append("")
    lines.append("- [Structure Annotations](#structure-annotations)")
    lines.append("- [Attribute Annotations](#attribute-annotations)")
    lines.append("- [Relationship Annotations](#relationship-annotations)")
    lines.append("- [Validation Rules](#validation-rules)")
    lines.append("- [Best Practices](#best-practices)")
    lines.append("- [Future Extensions](#future-extensions)")
    lines.append("")
    lines.append("---")
    lines.append("")
    
    # Annotations by category
    annotations = schema.get('annotations', {})
    
    # Structure Annotations
    lines.append("## Structure Annotations")
    lines.append("")
    lines.append("These annotations declare what C4 elements exist in "
                 "your system.")
    lines.append("")
    
    structure_annots = ['@c4-container', '@c4-component']
    for annot_name in structure_annots:
        if annot_name in annotations:
            lines.extend(_format_annotation(annot_name, 
                                           annotations[annot_name]))
    
    # Attribute Annotations
    lines.append("## Attribute Annotations")
    lines.append("")
    lines.append("These annotations describe properties of C4 elements.")
    lines.append("")
    
    attribute_annots = ['@c4-technology', '@c4-description', 
                        '@c4-responsibilities']
    for annot_name in attribute_annots:
        if annot_name in annotations:
            lines.extend(_format_annotation(annot_name, 
                                           annotations[annot_name]))
    
    # Relationship Annotations
    lines.append("## Relationship Annotations")
    lines.append("")
    lines.append("These annotations describe how C4 elements interact.")
    lines.append("")
    
    relationship_annots = ['@c4-uses', '@c4-used-by', 
                           '@c4-used-by-person', '@c4-operation', 
                           '@c4-calls', '@c4-relationship']
    for annot_name in relationship_annots:
        if annot_name in annotations:
            lines.extend(_format_annotation(annot_name, 
                                           annotations[annot_name]))
    
    # Validation Rules
    lines.append("## Validation Rules")
    lines.append("")
    validation = schema.get('validation_rules', {})
    for rule_name, rule_data in validation.items():
        lines.append(f"### {rule_name.replace('_', ' ').title()}")
        lines.append("")
        lines.append(rule_data.get('description', ''))
        lines.append("")
        if 'required' in rule_data:
            lines.append("**Required annotations:**")
            for req in rule_data['required']:
                lines.append(f"- `{req}`")
            lines.append("")
    
    # Best Practices
    lines.append("## Best Practices")
    lines.append("")
    best_practices = schema.get('best_practices', {})
    for practice_name, practice_text in best_practices.items():
        lines.append(f"### {practice_name.replace('_', ' ').title()}")
        lines.append("")
        lines.append(practice_text)
        lines.append("")
    
    # Future Extensions
    lines.append("## Future Extensions")
    lines.append("")
    lines.append("The following annotations are planned for future "
                 "versions:")
    lines.append("")
    future = schema.get('future_extensions', {}).get('planned', [])
    for item in future:
        lines.append(f"- `{item}`")
    lines.append("")
    
    # References
    lines.append("---")
    lines.append("")
    lines.append("## References")
    lines.append("")
    refs = schema.get('references', {})
    for ref_name, ref_url in refs.items():
        label = ref_name.replace('_', ' ').title()
        lines.append(f"- **{label}**: {ref_url}")
    lines.append("")
    
    # Write output
    with open(output_path, 'w') as f:
        f.write('\n'.join(lines))
    
    print(f"Generated {output_path}")


def _format_annotation(name: str, data: dict) -> list:
    """Format a single annotation as Markdown."""
    lines = []
    
    # Annotation header
    lines.append(f"### `{name}`")
    lines.append("")
    
    # Description
    if 'description' in data:
        lines.append(data['description'])
        lines.append("")
    
    # Format
    if 'format' in data:
        lines.append(f"**Format:** `{data['format']}`")
        lines.append("")
    
    # Placement
    if 'placement' in data:
        placement_str = ', '.join(f"`{p}`" for p in data['placement'])
        lines.append(f"**Placement:** {placement_str}")
        lines.append("")
    
    # Required attributes
    if 'required_attributes' in data:
        lines.append("**Required attributes:**")
        for attr in data['required_attributes']:
            lines.append(f"- `{attr}`")
        lines.append("")
    
    # Optional attributes
    if 'optional_attributes' in data:
        lines.append("**Optional attributes:**")
        for attr in data['optional_attributes']:
            lines.append(f"- `{attr}`")
        lines.append("")
    
    # Examples
    if 'examples' in data:
        lines.append("**Examples:**")
        lines.append("")
        lines.append("```python")
        for example in data['examples']:
            # Handle multi-line examples
            if '\n' in example:
                lines.append('"""')
                lines.append(example)
                lines.append('"""')
            else:
                lines.append(f'"""{example}"""')
        lines.append("```")
        lines.append("")
    
    # Notes
    if 'notes' in data:
        lines.append("**Notes:**")
        lines.append("")
        lines.append(data['notes'])
        lines.append("")
    
    # Special handling for component assignment
    if 'parent_container_assignment' in data:
        lines.append("**⚠️ Component Assignment:**")
        lines.append("")
        lines.append(data['parent_container_assignment'])
        lines.append("")
    
    lines.append("---")
    lines.append("")
    
    return lines


if __name__ == '__main__':
    schema_path = Path(__file__).parent / 'c4-annotations-schema.yaml'
    output_path = Path(__file__).parent / 'SCHEMA.md'
    
    generate_markdown(schema_path, output_path)