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):

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

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

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:

See class diagram: [Custodian](schemas/20251121/uml/mermaid/auto_generated/Custodian.md)

MkDocs

pip install mkdocs mkdocs-mermaid2-plugin

# mkdocs.yml
plugins:
  - mermaid2

Sphinx

pip install sphinxcontrib-mermaid

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

Static Site

# 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:

# 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:

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 ✅