2761857b0d
- Implemented `owl_to_mermaid.py` to convert OWL/Turtle files into Mermaid class diagrams. - Implemented `owl_to_plantuml.py` to convert OWL/Turtle files into PlantUML class diagrams. - Added two new PlantUML files for custodian multi-aspect diagrams.
174 lines
4.5 KiB
Markdown
174 lines
4.5 KiB
Markdown
# Final Clarification: Mermaid Output Files
|
|
|
|
## You Asked: "I still do not see the newly generated Mermaid file"
|
|
|
|
**Answer**: The "newly generated Mermaid files" **ARE** the 21 `.md` files!
|
|
|
|
They're not missing - they're **Markdown files with embedded Mermaid syntax**.
|
|
|
|
---
|
|
|
|
## Understanding the Two Output Types
|
|
|
|
### Type 1: `.md` files (LinkML Native) ✅ THIS IS WHAT YOU WANT
|
|
|
|
**What they are**: Markdown files with embedded Mermaid diagrams
|
|
|
|
**Example**: `Custodian.md` contains:
|
|
```markdown
|
|
```mermaid
|
|
classDiagram
|
|
class Custodian
|
|
Custodian : hc_id
|
|
Custodian : created
|
|
Custodian : modified
|
|
Custodian --> "*" CustodianAppellation : appellations
|
|
...
|
|
` ``
|
|
```
|
|
|
|
**How to view**:
|
|
1. **GitHub**: Push to GitHub → Open any `.md` file → Mermaid auto-renders
|
|
2. **VS Code**: Install "Markdown Preview Mermaid Support" extension → Open `.md` file → Click preview
|
|
3. **Browser**: Drag `.md` file to GitHub Gist → Auto-renders
|
|
|
|
**File list** (21 files):
|
|
```
|
|
Custodian.md (1.2KB)
|
|
CustodianLegalStatus.md (3.5KB)
|
|
CustodianName.md (1.7KB)
|
|
CustodianObservation.md (1.7KB)
|
|
ReconstructionActivity.md (1.5KB)
|
|
... (16 more classes)
|
|
```
|
|
|
|
**Generated by**: `gen-mermaid-class-diagram -d ../uml/mermaid 01_custodian_name_modular.yaml`
|
|
|
|
---
|
|
|
|
### Type 2: `.mmd` files (Custom Script) ⚠️ LESS USEFUL
|
|
|
|
**What they are**: Pure Mermaid syntax files (no Markdown wrapper)
|
|
|
|
**Example**: `custodian_multi_aspect_20251122_155319.mmd` contains:
|
|
```mermaid
|
|
classDiagram
|
|
class Custodian {
|
|
}
|
|
class CustodianLegalStatus {
|
|
}
|
|
... (all 35 classes in one file)
|
|
```
|
|
|
|
**How to view**:
|
|
1. Copy content to https://mermaid.live
|
|
2. Use Mermaid CLI to render: `mmdc -i file.mmd -o file.png`
|
|
|
|
**File list** (4 files, only 1 works):
|
|
```
|
|
custodian_multi_aspect_20251122_155319.mmd (1.6KB) ✅ WORKS
|
|
custodian_multi_aspect_20251122_155022.mmd (755B)
|
|
custodian_multi_aspect_20251122_155354.mmd (0B) ❌ EMPTY
|
|
custodian_multi_aspect_20251122_171150.mmd (0B) ❌ EMPTY
|
|
```
|
|
|
|
**Generated by**: `python3 scripts/owl_to_mermaid.py input.ttl output.mmd`
|
|
|
|
---
|
|
|
|
## The Confusion Explained
|
|
|
|
You expected to see files named like:
|
|
- `custodian_diagram.mmd`
|
|
- `ontology_visualization.mmd`
|
|
|
|
But what you got are:
|
|
- `Custodian.md` (Markdown with Mermaid inside)
|
|
- `CustodianLegalStatus.md` (Markdown with Mermaid inside)
|
|
- ... 19 more `.md` files
|
|
|
|
**These `.md` files ARE Mermaid diagrams** - just in Markdown format so they render nicely on GitHub!
|
|
|
|
---
|
|
|
|
## Quick Test
|
|
|
|
Let's verify the `.md` files contain Mermaid:
|
|
|
|
```bash
|
|
# Check Custodian.md
|
|
cat schemas/20251121/uml/mermaid/Custodian.md | head -20
|
|
|
|
# Output:
|
|
# ```mermaid
|
|
# classDiagram
|
|
# class Custodian
|
|
# click Custodian href "../Custodian"
|
|
# Custodian : appellations
|
|
# ...
|
|
# ```
|
|
```
|
|
|
|
**Proof**: The file starts with ` ```mermaid` - it's a Mermaid diagram!
|
|
|
|
---
|
|
|
|
## What You Should Do
|
|
|
|
### ✅ Use the `.md` files (21 individual class diagrams)
|
|
|
|
**Best for**:
|
|
- GitHub documentation
|
|
- Interactive exploration (clickable links)
|
|
- Per-class analysis
|
|
|
|
**How to view**:
|
|
```bash
|
|
# Push to GitHub
|
|
git add schemas/20251121/uml/mermaid/*.md
|
|
git commit -m "Add Mermaid class diagrams"
|
|
git push
|
|
|
|
# Then open on GitHub:
|
|
https://github.com/[your-org]/[your-repo]/blob/main/schemas/20251121/uml/mermaid/Custodian.md
|
|
```
|
|
|
|
### ⚠️ Or use the single `.mmd` file (comprehensive diagram)
|
|
|
|
**Only if you need**:
|
|
- Single file with all classes
|
|
- Mermaid Live Editor: https://mermaid.live
|
|
|
|
**Working file**: `custodian_multi_aspect_20251122_155319.mmd` (1.6KB)
|
|
|
|
---
|
|
|
|
## File Counts
|
|
|
|
| Type | Generator | Count | Status |
|
|
|------|-----------|-------|--------|
|
|
| `.md` files | `gen-mermaid-class-diagram` (LinkML) | 21 | ✅ ALL WORK |
|
|
| `.mmd` files | `owl_to_mermaid.py` (custom) | 4 | ⚠️ ONLY 1 WORKS |
|
|
|
|
**Recommendation**: Use the 21 `.md` files generated by LinkML's official tool.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
**The "newly generated Mermaid files" are the 21 `.md` files** in:
|
|
```
|
|
schemas/20251121/uml/mermaid/*.md
|
|
```
|
|
|
|
They're **not missing** - they're just in **Markdown format with embedded Mermaid syntax**, which is actually **better** because they auto-render on GitHub.
|
|
|
|
**To see them render**:
|
|
1. Open any `.md` file in VS Code with Mermaid extension
|
|
2. Or push to GitHub and view in browser
|
|
3. Or view the index: `cat schemas/20251121/uml/mermaid/index_20251122_171316.md`
|
|
|
|
---
|
|
|
|
**Bottom Line**: You have 21 working Mermaid diagrams in `.md` format. The `.mmd` files are a secondary output (single comprehensive diagram) and some are empty due to incomplete script runs.
|
|
|