lutaml 0.9.43 → 0.10.0

data/docs/_guides/diagram-generation.adoc

@@ -0,0 +1,316 @@
+---
+title: Diagram Generation Guide
+parent: Guides
+nav_order: 10
+---
+
+= EA-Style Diagram Generation
+
+LutaML can generate pixel-perfect SVG diagrams from Enterprise Architect (EA) models, matching EA's visual style exactly including colors, fonts, and layout.
+
+== Features
+
+* **EA-style colors**: DataType (pink #FFCCFF), FeatureType (yellow #FFFFCC), GML types (green #CCFFCC)
+* **Configurable styling**: Full YAML-based configuration system
+* **Multiple connector types**: Generalization, association, aggregation, composition, dependency
+* **Stereotype rendering**: Displays stereotypes in EA format («stereotype»)
+* **Lazy-loading in SPA mode**: Diagrams loaded on-demand for performance
+* **CLI extraction**: Extract diagrams individually or in batch
+* **Priority-based styling**: EA data > user config > built-in defaults
+
+== Quick Start
+
+=== Generate Diagram from QEA File
+
+[source,ruby]
+----
+require 'lutaml'
+
+# Load QEA file
+document = Lutaml::Qea.parse("model.qea")
+repo = Lutaml::UmlRepository::Repository.new(document: document)
+
+# Get a diagram
+diagram = repo.packages_index.flat_map(&:diagrams).first
+
+# Generate SVG
+presenter = Lutaml::UmlRepository::Presenters::DiagramPresenter.new(diagram, repo)
+svg = presenter.svg_output
+
+# Save to file
+File.write("diagram.svg", svg)
+----
+
+=== CLI Usage
+
+[source,bash]
+----
+# Extract single diagram
+lutaml diagram extract model.qea -d EAID_12345 -o diagram.svg
+
+# Extract all diagrams to directory
+lutaml diagram extract model.qea -o diagrams/
+
+# List all diagrams
+lutaml diagram list model.qea
+
+# Generate static site with diagrams
+lutaml generate-site model.qea -o output/
+----
+
+== Configuration
+
+Diagram styling is fully configurable via YAML. Create a `diagram_styles.yml` file:
+
+[source,yaml]
+----
+stereotypes:
+  DataType:
+    colors:
+      fill: "#FFCCFF"      # Pink for datatypes
+      stroke: "#000000"
+    fonts:
+      class_name:
+        weight: 700
+        style: "italic"
+
+  FeatureType:
+    colors:
+      fill: "#FFFFCC"      # Yellow for feature types
+      stroke: "#000000"
+
+defaults:
+  colors:
+    default_fill: "#E0E0E0"
+    default_stroke: "#000000"
+  fonts:
+    default:
+      family: "Carlito, Arial, sans-serif"
+      size: 9
+      weight: 400
+----
+
+=== Configuration Priority
+
+The style resolver merges styles from multiple sources with this priority:
+
+1. **EA Data** (highest) - Colors and styles from `.qea` file
+2. **User Configuration** - Your custom `diagram_styles.yml`
+3. **Built-in Defaults** (lowest) - Sensible EA-style defaults
+
+This ensures EA's original styling is preserved while allowing customization.
+
+=== Configuration Options
+
+==== Stereotypes
+
+Define styles for specific stereotypes:
+
+[source,yaml]
+----
+stereotypes:
+  Interface:
+    colors:
+      fill: "#FFFFEE"
+    fonts:
+      class_name:
+        style: "italic"
+----
+
+==== Packages
+
+Define styles for package hierarchies (supports wildcards):
+
+[source,yaml]
+----
+packages:
+  "CityGML::*":
+    colors:
+      fill: "#FFFFCC"
+----
+
+==== Classes
+
+Define styles for specific classes:
+
+[source,yaml]
+----
+classes:
+  Building:
+    colors:
+      fill: "#CCFFFF"
+----
+
+==== Connectors
+
+Customize connector appearance:
+
+[source,yaml]
+----
+connectors:
+  association:
+    arrow:
+      type: "open_arrow"
+      size: 8
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+    labels:
+      show_role_names: true
+      show_cardinality: true
+----
+
+== API Usage
+
+=== DiagramPresenter
+
+The main class for generating diagrams:
+
+[source,ruby]
+----
+presenter = Lutaml::UmlRepository::Presenters::DiagramPresenter.new(
+  diagram,
+  repository,
+  config_path: "custom_styles.yml"  # Optional
+)
+
+# Generate SVG
+svg = presenter.svg_output(
+  padding: 20,                     # Padding around diagram
+  background_color: "#ffffff",     # Background color
+  grid_visible: false,             # Show grid
+  interactive: false               # Enable click handlers
+)
+----
+
+=== Accessing Diagram Data
+
+[source,ruby]
+----
+# Get all diagrams
+diagrams = repo.packages_index.flat_map(&:diagrams).compact
+
+# Find specific diagram
+diagram = diagrams.find { |d| d.xmi_id.include?("EAID_12345") }
+
+# Get diagram info
+puts "Name: #{diagram.name}"
+puts "Type: #{diagram.diagram_type}"
+puts "Elements: #{diagram.diagram_objects.count}"
+puts "Links: #{diagram.diagram_links.count}"
+----
+
+== Architecture
+
+=== Component Overview
+
+[source]
+----
+DiagramPresenter
+    │
+    ├─> LayoutEngine (coordinate conversion)
+    ├─> StyleResolver (style merging)
+    ├─> SvgRenderer (SVG generation)
+    │       │
+    │       ├─> ElementRenderers (class, package, etc.)
+    │       └─> PathBuilder (connector routing)
+    │
+    └─> Configuration (YAML config loading)
+----
+
+=== Key Components
+
+* **DiagramPresenter**: Coordinates the entire rendering pipeline
+* **LayoutEngine**: Converts EA coordinates (left/top/right/bottom) to SVG (x/y/width/height)
+* **StyleResolver**: Merges EA data + user config + defaults with priority system
+* **SvgRenderer**: Generates complete SVG with layers (background, connectors, elements)
+* **PathBuilder**: Parses EA geometry strings and builds SVG paths
+* **ElementRenderers**: Render specific element types (classes, packages, etc.)
+
+== Coordinate System
+
+EA uses a different coordinate system than SVG:
+
+* **EA**: Uses left/top/right/bottom for element bounds
+* **SVG**: Uses x/y/width/height
+
+The LayoutEngine automatically converts between these:
+
+[source,ruby]
+----
+# EA coordinates
+diagram_object.left   # Left edge
+diagram_object.top    # Top edge
+diagram_object.right  # Right edge
+diagram_object.bottom # Bottom edge
+
+# Converted to SVG
+{
+  x: left,
+  y: top,
+  width: right - left,
+  height: bottom - top
+}
+----
+
+== Troubleshooting
+
+=== Diagrams Not Appearing
+
+1. Check that diagrams exist in the QEA file:
++
+[source,bash]
+----
+lutaml diagram list model.qea
+----
+
+2. Verify diagram has visual elements:
++
+[source,ruby]
+----
+puts "Objects: #{diagram.diagram_objects.count}"
+puts "Links: #{diagram.diagram_links.count}"
+----
+
+=== Colors Not Matching EA
+
+1. Check if EA data exists in diagram_object.style
+2. Verify configuration file is being loaded
+3. Check stereotype names match exactly (case-sensitive)
+
+=== Elements Positioned Incorrectly
+
+EA coordinates may have negative values. The LayoutEngine should normalize these, but you can verify:
+
+[source,ruby]
+----
+diagram.diagram_objects.each do |obj|
+  puts "#{obj.object_xmi_id}: (#{obj.left}, #{obj.top})"
+end
+----
+
+== Performance
+
+Diagram generation is optimized for both single and batch operations:
+
+* **Single diagram**: <1 second
+* **Batch (100 diagrams)**: ~2 minutes
+* **Memory usage**: Modest, processes one diagram at a time
+
+For large batches, diagrams are generated and saved incrementally to avoid memory issues.
+
+== Future Enhancements
+
+Planned features for future releases:
+
+* **PNG/PDF export**: Generate raster and PDF formats
+* **Interactive diagrams**: Click handlers and tooltips
+* **Diagram comparison**: Visual diff between versions
+* **Custom themes**: Pre-built color schemes
+* **Legend generation**: Auto-generate color legends
+
+== See Also
+
+* link:diagram-configuration[Complete Configuration Reference]
+* link:../README[LutaML README]
+* link:../config/diagram_styles.yml[Default Styles]

data/docs/_guides/index.adoc

@@ -0,0 +1,135 @@
+= Guides
+:nav_order: 3
+:has_children: true
+
+== Overview
+
+This section provides task-oriented how-to documentation for common workflows and operations with LutaML. Each guide focuses on accomplishing a specific goal.
+
+== Command-Line Usage
+
+=== link:../cli-usage[Complete CLI Guide]
+
+Comprehensive guide to using LutaML's command-line interface, including all commands, options, and workflows.
+
+== Diagram Generation
+
+=== link:diagram-generation[Generating EA-Style Diagrams]
+
+Learn how to generate pixel-perfect SVG diagrams from Enterprise Architect models with full styling support.
+
+**Topics covered:**
+
+* EA-style colors and fonts
+* Configurable styling system
+* Multiple connector types
+* Lazy-loading in SPA mode
+
+== Modeling Languages
+
+=== link:uml-modeling[UML Modeling with LutaML]
+
+Work with UML class diagrams using LutaML's native syntax and conversion tools.
+
+=== link:sysml-modeling[SysML Modeling with LutaML]
+
+Extend UML with SysML concepts for systems engineering and MBSE workflows.
+
+== Configuration & Customization
+
+=== link:../references/configuration/diagram-styles[Configuring Diagram Styles]
+
+Learn how to customize diagram colors, fonts, and styling using YAML configuration files.
+
+=== link:../references/configuration/package-metadata[Setting Up Package Metadata]
+
+Configure XML namespaces, schema locations, and other metadata for UML packages.
+
+=== link:repository-management[Managing Repositories]
+
+Best practices for organizing, versioning, and maintaining LUR repositories.
+
+== Parsing Guides
+
+=== link:parsing/qea-parsing[Parsing QEA Files]
+
+How to parse Enterprise Architect QEA files directly from SQLite databases.
+
+**Topics covered:**
+
+* File validation
+* Performance optimization
+* Handling large models
+* Error recovery
+
+=== link:parsing/xmi-parsing[Parsing XMI Files]
+
+Working with OMG XMI format exports from various UML tools.
+
+**Topics covered:**
+
+* XMI format detection
+* Namespace handling
+* Profile support
+* Validation
+
+=== link:parsing/express-parsing[Parsing EXPRESS Schemas]
+
+Handle ISO 10303-11 EXPRESS schemas used in industrial standards.
+
+**Topics covered:**
+
+* Schema file parsing
+* Cache files
+* Model transformation
+* Integration with Expressir
+
+== Working with Models
+
+=== Querying and Search
+
+* Full-text search across models
+* Using the query DSL effectively
+* Filtering by properties
+* Pattern matching
+
+=== Export and Integration
+
+* Exporting to CSV/JSON/YAML
+* Generating documentation
+* Integration with other tools
+* Custom exporters
+
+== Advanced Topics
+
+=== Performance Optimization
+
+* LUR caching strategies
+* Lazy loading
+* Memory management
+* Batch processing
+
+=== Extending LutaML
+
+* Custom parsers
+* Plugin development
+* Transformer creation
+* Renderer extensions
+
+== Guide Format
+
+Each guide follows this structure:
+
+1. **Purpose** - What this guide helps you accomplish
+2. **Prerequisites** - What you need to know or have installed
+3. **Concepts** - Key concepts for understanding
+4. **Step-by-Step Instructions** - Detailed walkthrough
+5. **Examples** - Real-world examples
+6. **Troubleshooting** - Common issues and solutions
+7. **References** - Related documentation
+
+== Related Sections
+
+* link:../tutorials[Tutorials] - Step-by-step learning paths
+* link:../pages[Core Topics] - Fundamental concepts
+* link:../references[Reference] - Detailed specifications

data/docs/{lutaml-express.adoc → _guides/parsing/express-parsing.adoc}

@@ -1,3 +1,10 @@
+---
+title: EXPRESS Parsing
+parent: Parsing Guides
+grand_parent: Guides
+nav_order: 1
+---
+
 = Lutaml::Express
 
 Lutaml::Express provides functionality to parse and manipulate EXPRESS files,

data/docs/_guides/parsing/index.adoc

@@ -0,0 +1,77 @@
+---
+title: Parsing Guides
+parent: Guides
+nav_order: 20
+has_children: true
+---
+
+= Parsing Guides
+
+Comprehensive guides for parsing different model formats with LutaML.
+
+== Available Parsing Guides
+
+=== link:express-parsing[EXPRESS Parsing]
+
+Guide for parsing ISO 10303-11 EXPRESS schemas used in industrial standards.
+
+**Topics covered:**
+
+* Schema file parsing with Expressir
+* Cache file handling
+* Model transformation
+* Integration examples
+
+=== link:xmi-parsing[XMI Parsing]
+
+Guide for parsing OMG XMI format exports from UML tools.
+
+**Topics covered:**
+
+* XMI format detection
+* Namespace handling
+* Profile support
+* Validation techniques
+
+=== QEA Parsing
+
+Enterprise Architect QEA format parsing is covered in multiple locations:
+
+* link:../../pages/concepts/qea-parsing[Concept Overview] - Understanding QEA
+* link:../../references/formats/qea-structure[Format Specification] - Complete details
+* link:../../tutorials/getting-started[Tutorial] - Step-by-step walkthrough
+
+== Common Parsing Patterns
+
+=== Using the Unified Parser
+
+LutaML provides a single entry point for all formats:
+
+[source,ruby]
+----
+require "lutaml"
+
+# Automatically detects format and parses
+document = Lutaml::Parser.parse([File.new("model.xmi")])
+document = Lutaml::Parser.parse([File.new("model.qea")])
+document = Lutaml::Parser.parse([File.new("schema.exp")])
+----
+
+=== Error Handling
+
+All parsers follow consistent error handling:
+
+[source,ruby]
+----
+begin
+  document = Lutaml::Parser.parse([File.new("model.xmi")])
+rescue Lutaml::ParseError => e
+  puts "Parse error: #{e.message}"
+end
+----
+
+== Related Documentation
+
+* link:../../references/formats[Format Specifications] - Technical details
+* link:../../tutorials/getting-started[Getting Started] - Basic parsing tutorial
+* link:../../references/api/parsers[Parser API Reference] - Complete API docs

data/docs/{lutaml-xmi.adoc → _guides/parsing/xmi-parsing.adoc}

@@ -1,3 +1,10 @@
+---
+title: XMI Parsing
+parent: Parsing Guides
+grand_parent: Guides
+nav_order: 2
+---
+
 = Lutaml::XMI
 
 Lutaml::XMI provides functionality to parse and manipulate

data/docs/_guides/sysml-modeling.adoc

@@ -0,0 +1,37 @@
+---
+title: SysML Modeling with LutaML
+parent: Guides
+nav_order: 12
+---
+
+= Lutaml::Sysml
+
+Lutaml::Sysml extends Lutaml::Uml by adding concepts relevant to systems
+engineering, supporting a Model-Based Systems Engineering (MBSE) approach
+throughout the entire system lifecycle.
+
+== Overview
+
+SysML (Systems Modeling Language) is a general-purpose modeling language for systems engineering applications. It supports the specification, analysis, design, verification, and validation of complex systems that may include hardware, software, data, personnel, procedures, and facilities.
+
+== Usage
+
+Lutaml::Sysml provides specialized diagram types and elements for systems engineering modeling, including:
+
+* Requirements diagrams
+* Block definition diagrams
+* Internal block diagrams
+* Parametric diagrams
+* Activity diagrams
+* Sequence diagrams
+* State machine diagrams
+* Use case diagrams
+
+== Integration with UML
+
+Since SysML extends UML, all UML modeling capabilities are available in SysML models. The extension adds systems engineering-specific stereotypes, properties, and diagram types while maintaining compatibility with the UML foundation.
+
+== See Also
+
+* link:uml-modeling[UML Modeling Guide]
+* link:../README[LutaML Documentation]

data/docs/{lutaml-uml.adoc → _guides/uml-modeling.adoc}

@@ -1,3 +1,9 @@
+---
+title: UML Modeling with LutaML
+parent: Guides
+nav_order: 11
+---
+
 = Lutaml::Uml
 
 Lutaml::Uml is a language for specifying UML class diagrams and a tool for
@@ -5,7 +11,7 @@ converting it into various different formats.
 
 == Language
 
-See link:lutaml_syntax.adoc[LutaML syntax]
+See link:lutaml_syntax[LutaML syntax]
 
 == Usages
 
@@ -102,7 +108,7 @@ diagram Address {
   caption ''
   association {
     owner_type aggregation
-    owner 
+    owner
     member_type direct
     member AddressComponent
   }