glam/UML_GENERATION_LINKML_AUTO.md

# LinkML-Generated UML Diagrams & Documentation - COMPLETE ✅

**Date**: 2025-11-24 00:35:00  
**Method**: Official LinkML generators (not manual Mermaid)  
**Generated**: 53 Mermaid class diagrams + 377 markdown documentation files

---

## What Was Generated

### 1. Mermaid Class Diagrams (53 files)

**Location**: `schemas/20251121/uml/mermaid/auto_generated/`  
**Generator**: `MermaidClassDiagramGenerator` (LinkML 1.9.5)  
**Format**: Individual markdown files with embedded Mermaid syntax

**Key Diagrams**:
- `Custodian.md` - Central hub entity with all relationships
- `EncompassingBody.md` - Organizational relationships hierarchy
- `CustodianName.md` - Name aspect
- `CustodianPlace.md` - Place aspect
- `CustodianLegalStatus.md` - Legal status aspect
- `CustodianType.md` - Type classification
- `CustodianCollection.md` - Collections
- `OrganizationalStructure.md` - Internal structure
- `UmbrellaOrganisation.md`, `NetworkOrganisation.md`, `Consortium.md` - 3 EncompassingBody types

**Statistics**:
- **Total files**: 53 markdown files
- **Total size**: 212 KB
- **Format**: Mermaid classDiagram syntax with clickable links

**Example Output** (EncompassingBody.md):
```mermaid
classDiagram
    class EncompassingBody
    click EncompassingBody href "../EncompassingBody"
      EncompassingBody <|-- UmbrellaOrganisation
        click UmbrellaOrganisation href "../UmbrellaOrganisation"
      EncompassingBody <|-- NetworkOrganisation
        click NetworkOrganisation href "../NetworkOrganisation"
      EncompassingBody <|-- Consortium
        click Consortium href "../Consortium"
      
      EncompassingBody : description
      EncompassingBody : dissolution_date
      EncompassingBody : founding_date
      EncompassingBody : id
      EncompassingBody : member_custodians
      
      EncompassingBody --> "1" EncompassingBodyTypeEnum : organization_type
        click EncompassingBodyTypeEnum href "../EncompassingBodyTypeEnum"
```

---

### 2. Full Schema Documentation (377 files)

**Location**: `schemas/20251121/docs/20251124_003435/`  
**Generator**: `gen-doc` (LinkML documentation generator)  
**Format**: Markdown with embedded Mermaid diagrams

**Key Documentation Files**:
- `index.md` (37 KB) - Schema overview with all classes, enums, slots
- `Custodian.md` (71 KB) - Complete Custodian class documentation
- `EncompassingBody.md` (37 KB) - EncompassingBody hierarchy docs
- Individual files for every class, slot, enum, and type

**Statistics**:
- **Total files**: 377 markdown files
- **Total size**: 3.5 MB
- **Includes**: Class definitions, inheritance, slots, examples, mappings

**Documentation Structure**:
Each class documentation includes:
1. **Description** - Full class documentation from LinkML schema
2. **URI** - Ontology URI mapping (e.g., `org:Organization`)
3. **Mermaid Class Diagram** - Visual representation with inheritance
4. **Inheritance** - Parent/child class relationships
5. **Slots** - All properties with descriptions and ranges
6. **Mappings** - Exact/close/related mappings to base ontologies
7. **Identifier Prefixes** - Namespace mappings

---

## Generation Commands

### Generate Mermaid Class Diagrams

```bash
python << 'EOF'
from linkml.generators.mermaidclassdiagramgen import MermaidClassDiagramGenerator

# Generate class diagrams for all classes
gen = MermaidClassDiagramGenerator(
    'schemas/20251121/linkml/01_custodian_name_modular.yaml',
    directory='schemas/20251121/uml/mermaid/auto_generated'
)

gen.generate_class_diagrams()
print('✅ Generated Mermaid class diagrams')
EOF
```

**Output**: One `.md` file per class in the specified directory

---

### Generate Full Documentation

```bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

gen-doc schemas/20251121/linkml/01_custodian_name_modular.yaml \
  -d schemas/20251121/docs/${TIMESTAMP}
```

**Output**: Complete documentation site with:
- `index.md` - Schema overview
- One `.md` file per class/enum/slot/type
- Embedded Mermaid diagrams
- Ontology mappings
- Examples

---

## Advantages Over Manual Mermaid

### ✅ Official LinkML Output
- Generated directly from LinkML schema (no manual translation)
- Always matches current schema structure
- Updates automatically when schema changes

### ✅ Complete Coverage
- **53 class diagrams** (every class in schema)
- **377 documentation files** (classes, slots, enums, types)
- Nothing missed - exhaustive coverage

### ✅ Standardized Format
- Consistent diagram style across all classes
- Standard LinkML documentation format
- Clickable links between related entities

### ✅ Regenerable
- Single command regenerates all diagrams
- No manual maintenance required
- Version controlled (timestamped directories)

### ✅ Integration Ready
- Works with MkDocs, Sphinx, GitHub Pages
- Markdown format renders everywhere
- Can export to HTML, PDF, etc.

---

## Comparison: Manual vs. Auto-Generated

| Aspect | Manual Mermaid | LinkML Auto-Generated |
|--------|----------------|----------------------|
| **Coverage** | 4 diagrams (selective) | 53 diagrams (exhaustive) |
| **Accuracy** | Manual translation (error-prone) | Direct from schema (accurate) |
| **Maintenance** | Update manually on schema changes | Regenerate with one command |
| **Ontology URIs** | Manually added as notes | Automatically included |
| **Slot definitions** | Manually curated | Complete from schema |
| **Inheritance** | Manually drawn | Automatically resolved |
| **Links** | Static | Clickable between entities |
| **Documentation** | Separate files | Integrated |
| **Total size** | 28 KB (4 files) | 3.7 MB (430 files) |

---

## What to Keep

### Keep Manual Mermaid For:
1. **High-level architecture diagrams** - Multi-aspect temporal architecture
2. **Use case examples** - Real-world scenarios with color coding
3. **Process flows** - Observation → Reconstruction → Aspects
4. **Documentation narratives** - Story-driven explanations

### Use LinkML Auto-Generated For:
1. **Class reference** - Definitive class structure
2. **API documentation** - Complete slot listings
3. **Ontology mappings** - URIs and exact mappings
4. **Schema changes** - Always up-to-date
5. **Comprehensive coverage** - All classes, not just highlights

---

## Directory Structure

```
schemas/20251121/
├── uml/
│   └── mermaid/
│       ├── auto_generated/           # ✅ NEW: LinkML-generated
│       │   ├── Custodian.md          # 53 class diagrams
│       │   ├── EncompassingBody.md
│       │   └── ...
│       ├── EncompassingBody_20251124_002500.mmd        # Manual (keep)
│       ├── EncompassingBody_examples_20251124_002700.mmd  # Manual (keep)
│       └── multi_aspect_temporal_architecture_20251124_002800.mmd  # Manual (keep)
│
└── docs/
    └── 20251124_003435/              # ✅ NEW: Full documentation
        ├── index.md                   # 377 markdown files
        ├── Custodian.md
        ├── EncompassingBody.md
        └── ...
```

---

## Rendering the Diagrams

### GitHub/GitLab
Markdown files with Mermaid render automatically:
```markdown
See class diagram: [Custodian](schemas/20251121/uml/mermaid/auto_generated/Custodian.md)
```

### MkDocs
```bash
pip install mkdocs mkdocs-mermaid2-plugin

# mkdocs.yml
plugins:
  - mermaid2
```

### Sphinx
```bash
pip install sphinxcontrib-mermaid

# conf.py
extensions = ['sphinxcontrib.mermaid']
```

### Static Site
```bash
# Convert to HTML
npm install -g @mermaid-js/mermaid-cli

for file in schemas/20251121/uml/mermaid/auto_generated/*.md; do
  mmdc -i "$file" -o "${file%.md}.html"
done
```

### VS Code
Install extension: "Markdown Preview Mermaid Support"

---

## Regeneration Workflow

When schema changes:

```bash
# 1. Update LinkML schema files
vim schemas/20251121/linkml/...

# 2. Regenerate RDF
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
gen-owl -f ttl schemas/20251121/linkml/01_custodian_name_modular.yaml \
  > schemas/20251121/rdf/01_custodian_name_modular_${TIMESTAMP}.owl.ttl

# 3. Regenerate Mermaid diagrams
python << 'EOF'
from linkml.generators.mermaidclassdiagramgen import MermaidClassDiagramGenerator
gen = MermaidClassDiagramGenerator(
    'schemas/20251121/linkml/01_custodian_name_modular.yaml',
    directory='schemas/20251121/uml/mermaid/auto_generated'
)
gen.generate_class_diagrams()
EOF

# 4. Regenerate documentation
gen-doc schemas/20251121/linkml/01_custodian_name_modular.yaml \
  -d schemas/20251121/docs/${TIMESTAMP}

# 5. Update manual narrative diagrams if needed (optional)
# Edit: EncompassingBody_examples_*.mmd
#       multi_aspect_temporal_architecture_*.mmd
```

---

## Integration with Documentation Sites

### Example: MkDocs Site

**Project structure**:
```
docs/
├── index.md
├── getting-started.md
├── schema/
│   ├── overview.md
│   └── classes/
│       ├── Custodian.md → ../../schemas/20251121/uml/mermaid/auto_generated/Custodian.md
│       └── EncompassingBody.md → ../../schemas/20251121/uml/mermaid/auto_generated/EncompassingBody.md
└── examples/
    └── encompassing-body.md

mkdocs.yml:
site_name: Heritage Custodian Ontology
plugins:
  - mermaid2
nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Schema:
    - Overview: schema/overview.md
    - Classes: schema/classes/
  - Examples: examples/
```

### Example: Sphinx Site

**conf.py**:
```python
extensions = [
    'sphinxcontrib.mermaid',
    'recommonmark',
]

mermaid_version = '9.4.0'
```

---

## Statistics Summary

### LinkML Auto-Generated
- **Mermaid class diagrams**: 53 files (212 KB)
- **Full documentation**: 377 files (3.5 MB)
- **Total**: 430 files (3.7 MB)

### Manual Narrative Diagrams (Keep)
- **Architecture overview**: 1 file (6.7 KB)
- **Use case examples**: 1 file (2.4 KB)
- **Process flows**: 1 file (4.1 KB)
- **Total**: 3 files (13.2 KB)

### Combined Total
- **433 visualization/documentation files**
- **3.71 MB total**

---

## Key Insights

### What We Learned

1. **gen-yuml is deprecated** - Use `MermaidClassDiagramGenerator` instead
2. **One diagram per class** - Not a single monolithic diagram
3. **Embedded in markdown** - Easy to render in docs
4. **Clickable links** - Navigate between related classes
5. **gen-doc is comprehensive** - Full schema documentation with diagrams

### Best Practices

1. **Use auto-generated for reference** - Always accurate, always up-to-date
2. **Use manual for narratives** - Architecture stories, use cases, flows
3. **Regenerate on schema changes** - Keep visualizations in sync
4. **Version with timestamps** - Track evolution over time
5. **Integrate into docs site** - Make diagrams discoverable

---

## Related Documentation

- **Schema Files**: `schemas/20251121/linkml/01_custodian_name_modular.yaml`
- **RDF Generation**: `MAIN_SCHEMA_RDF_GENERATION_COMPLETE.md`
- **Session Summary**: `SESSION_COMPLETE_ENCOMPASSING_BODY_MAIN_SCHEMA.md`
- **Manual Diagrams**: `UML_GENERATION_COMPLETE.md` (now deprecated for class diagrams)

---

## Status

| Component | Method | Files | Size | Status |
|-----------|--------|-------|------|--------|
| **Mermaid Class Diagrams** | LinkML auto | 53 | 212 KB | ✅ DONE |
| **Full Documentation** | LinkML auto | 377 | 3.5 MB | ✅ DONE |
| **Manual Architecture** | Manual | 3 | 13 KB | ✅ KEEP |
| **TOTAL** | Mixed | **433** | **3.71 MB** | ✅ COMPLETE |

---

## Next Steps (Optional)

1. **Setup MkDocs Site** - Create documentation website
2. **Export to HTML** - Static HTML versions of diagrams
3. **Add to GitHub Pages** - Publish documentation online
4. **Create CI/CD Pipeline** - Auto-regenerate on schema push

---

**Heritage Custodian Ontology v0.2.2**  
**LinkML-Generated UML & Documentation - COMPLETE** ✅