lutaml 0.11.5 → 0.11.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/docs.yml +28 -5
  3. data/.github/workflows/links.yml +14 -0
  4. data/docs/_config.yml +1 -1
  5. data/docs/_guides/cli-usage.adoc +43 -0
  6. data/docs/_guides/diagram-generation.adoc +3 -3
  7. data/docs/_guides/index.adoc +21 -20
  8. data/docs/_guides/parsing/index.adoc +9 -8
  9. data/docs/_guides/parsing/qea-parsing.adoc +47 -0
  10. data/docs/_guides/repository-management.adoc +44 -0
  11. data/docs/_guides/sysml-modeling.adoc +2 -2
  12. data/docs/_guides/uml-modeling.adoc +1 -1
  13. data/docs/_pages/concepts/diagram-generation.adoc +4 -4
  14. data/docs/_pages/concepts/lur-format.adoc +4 -4
  15. data/docs/_pages/concepts/qea-parsing.adoc +4 -4
  16. data/docs/_pages/concepts/uml-models.adoc +43 -0
  17. data/docs/_pages/core/architecture.adoc +4 -4
  18. data/docs/_pages/core/installation.adoc +7 -7
  19. data/docs/_pages/core/overview.adoc +10 -10
  20. data/docs/_pages/index.adoc +11 -10
  21. data/docs/_references/api/parsers.adoc +61 -0
  22. data/docs/_references/api/presenters.adoc +43 -0
  23. data/docs/_references/api/repository.adoc +67 -0
  24. data/docs/_references/cli/commands.adoc +72 -0
  25. data/docs/_references/configuration/diagram-styles.adoc +3 -3
  26. data/docs/_references/configuration/index.adoc +5 -4
  27. data/docs/_references/configuration/package-metadata.adoc +4 -4
  28. data/docs/_references/formats/index.adoc +5 -4
  29. data/docs/_references/formats/lur-format.adoc +39 -0
  30. data/docs/_references/formats/qea-structure.adoc +4 -4
  31. data/docs/_references/index.adoc +26 -25
  32. data/docs/_tutorials/documentation-site.adoc +47 -0
  33. data/docs/_tutorials/first-lur-package.adoc +45 -0
  34. data/docs/_tutorials/generating-diagrams.adoc +42 -0
  35. data/docs/_tutorials/getting-started.adoc +45 -0
  36. data/docs/_tutorials/index.adoc +28 -37
  37. data/docs/_tutorials/querying-models.adoc +44 -0
  38. data/docs/examples/build_package.rb +12 -0
  39. data/docs/examples/build_site.rb +12 -0
  40. data/docs/examples/city_model.rb +21 -0
  41. data/docs/examples/present_class.rb +10 -0
  42. data/docs/examples/query_model.rb +12 -0
  43. data/docs/examples/render_diagram.rb +11 -0
  44. data/docs/index.adoc +12 -12
  45. data/docs/lychee.toml +24 -57
  46. data/lib/lutaml/version.rb +1 -1
  47. data/lutaml.gemspec +1 -1
  48. data/scripts/check-site-urls.rb +54 -0
  49. data/scripts/check-vendor-link.py +64 -0
  50. metadata +26 -4
@@ -0,0 +1,61 @@
1
+ ---
2
+ permalink: /references/api/parsers/
3
+ title: Parser APIs
4
+ parent: Reference
5
+ ---
6
+ = Parser APIs
7
+
8
+ Select the parser for the input language and check its result type before
9
+ passing the result to another component. The split gems do not share a
10
+ universal `Lutaml::Parser.parse` entry point.
11
+
12
+ [cols="1,2,2",options="header"]
13
+ |===
14
+ |Input |Entry point |Result
15
+ |LML text |`Lutaml::Lml.parse_document(input)` |`Lutaml::Lml::Document`, without view resolution.
16
+ |LML diagram/view |`Lutaml::Lml.parse(input)` |An LML document with view imports and filtering resolved.
17
+ |EXPRESS |`Lutaml::Express::Parsers::Exp.parse(io)` |The EXPRESS repository returned by Expressir.
18
+ |LUR package |`Lutaml::UmlRepository::Repository.from_package(path)` |A UML repository.
19
+ |QEA or XMI |A separately installed format provider |A provider-specific result; convert it to a UML document before repository construction.
20
+ |===
21
+
22
+ == LML input
23
+
24
+ [source,ruby]
25
+ ----
26
+ require "lutaml"
27
+
28
+ document = Lutaml::Lml.parse_document("diagram City { class Building {} }")
29
+ puts document.classes.first.name
30
+ ----
31
+
32
+ This prints `Building`. For files, open the input and pass the IO object.
33
+ `parse` performs the additional view-resolution stage needed by diagram views.
34
+ Parsing failures raise LML errors such as `Lutaml::Lml::ParsingError`.
35
+ Do not treat an LML document as a `Lutaml::Uml::Document` merely because both
36
+ have a `classes` collection.
37
+
38
+ == EXPRESS input
39
+
40
+ Pass an open IO to the umbrella's EXPRESS adapter:
41
+
42
+ [source,ruby]
43
+ ----
44
+ require "lutaml"
45
+
46
+ repository = File.open("schema.exp") do |input|
47
+ Lutaml::Express::Parsers::Exp.parse(input)
48
+ end
49
+ ----
50
+
51
+ The result belongs to Expressir's model family. Use Expressir's repository
52
+ operations rather than the UML query API on that result.
53
+
54
+ == QEA and XMI integration
55
+
56
+ `lutaml-uml` 1.0.3's repository layer does not import QEA or XMI itself.
57
+ Its `from_file` method raises `ArgumentError` for those extensions.
58
+ An importer must supply a `Lutaml::Uml::Document`; then use
59
+ `Repository.from_document(document)`.
60
+ See link:{site-baseurl}/guides/parsing/qea-parsing/[Integrating QEA Parsing]
61
+ for the integration boundary and validation steps.
@@ -0,0 +1,43 @@
1
+ ---
2
+ permalink: /references/api/presenters/
3
+ title: Presenter APIs
4
+ parent: Reference
5
+ ---
6
+ = Presenter APIs
7
+
8
+ Presenters turn UML elements into text, table rows, and hashes without changing
9
+ the model. They live under `Lutaml::UmlRepository::Presenters`.
10
+
11
+ == Present a class
12
+
13
+ Save this beside `city_model.rb` from
14
+ link:{site-baseurl}/tutorials/getting-started/[Getting Started]:
15
+
16
+ [source,ruby]
17
+ ----
18
+ include::../../examples/present_class.rb[]
19
+ ----
20
+
21
+ Run it with `bundle exec ruby present_class.rb`. The output starts with
22
+ `Class: Building`. Requiring the concrete class presenter registers it with
23
+ the factory before the factory selects it.
24
+
25
+ == Factory and output contract
26
+
27
+ `PresenterFactory.create(element, repository = nil, context = nil)` chooses
28
+ a registered presenter by the element's class, then by its ancestors.
29
+ It raises `ArgumentError` if no presenter is registered for the type.
30
+
31
+ Concrete presenters implement:
32
+
33
+ * `to_text`: a text description.
34
+ * `to_table_row`: a hash suitable for a table row.
35
+ * `to_hash`: structured output for callers to serialize as JSON or YAML.
36
+
37
+ The base `ElementPresenter` provides shared helpers; it does not implement
38
+ those output methods. Instantiate a concrete presenter instead.
39
+
40
+ For an application-specific type, subclass the base, implement all three
41
+ outputs as public methods, then call
42
+ `PresenterFactory.register(element_class, presenter_class)`.
43
+ Keep the repository argument when output needs qualified names or relationships.
@@ -0,0 +1,67 @@
1
+ ---
2
+ permalink: /references/api/repository/
3
+ title: Repository API
4
+ parent: Reference
5
+ ---
6
+ = Repository API
7
+
8
+ `Lutaml::UmlRepository::Repository`, supplied by `lutaml-uml`, wraps a
9
+ `Lutaml::Uml::Document` with indexes, queries, statistics, and package I/O.
10
+ Load it with `require "lutaml"` when using the umbrella gem.
11
+
12
+ == Construction and package I/O
13
+
14
+ [cols="2,3",options="header"]
15
+ |===
16
+ |Method |Contract
17
+ |`.from_document(document, options = {})` |Build indexes for a typed UML document.
18
+ |`.from_package(path)` |Load a LUR ZIP package, including its stored indexes.
19
+ |`.from_file(path, options = {})` |Accept `.lur` files; reject other extensions with `ArgumentError`.
20
+ |`.from_package_lazy(path)` |Load the document and defer index construction.
21
+ |`#export_to_package(path, options = {})` |Write a LUR package from the repository.
22
+ |===
23
+
24
+ For export with `lutaml-uml` 1.0.3, also require `lutaml/uml/version` to load the
25
+ component version used in package metadata. See the executable
26
+ link:{site-baseurl}/tutorials/first-lur-package/[LUR package tutorial].
27
+
28
+ `.from_file_cached(source_path, lur_path: nil) { |path| ... }` uses an existing
29
+ cache when it is at least as new as the source. Otherwise, the block must
30
+ return a UML document to index and save. The method does not choose an external
31
+ QEA or XMI parser for you.
32
+
33
+ == Lookups
34
+
35
+ * `find_package(path, raise_on_error: false)` and
36
+ `find_class(qualified_name, raise_on_error: false)` return an element or `nil`.
37
+ * `list_packages(path = "ModelRoot", recursive: false)` returns package objects.
38
+ * `classes_in_package(path, recursive: false)` returns matching classifiers.
39
+ * `find_classes_by_stereotype(name)` uses the stereotype index.
40
+ * `package_tree(path = "ModelRoot", max_depth: nil)` returns the package hierarchy.
41
+ * `find_diagram(name)`, `diagrams_in_package(path)`, and `all_diagrams` access
42
+ diagram objects already present in the document; they do not render SVG.
43
+
44
+ Qualified paths use `::`, for example `ModelRoot::City::Building`.
45
+ Use the actual package hierarchy rather than a source filename as the path.
46
+
47
+ == Search, queries, and statistics
48
+
49
+ `search(text, types: [:class, :attribute, :association], fields: [:name])`
50
+ returns grouped results under `:classes`, `:attributes`, and `:associations`,
51
+ plus `:total`. Structured queries return model objects:
52
+
53
+ [source,ruby]
54
+ ----
55
+ classes = repository.query do |query|
56
+ query.classes.where(name: /Building/).order_by(:name).limit(10)
57
+ end.all
58
+ ----
59
+
60
+ In `lutaml-uml` 1.0.3, the DSL's `in_package` condition raises `NameError` for
61
+ an unresolved `PackagePath` constant. Use `classes_in_package(path)` for that
62
+ operation rather than adding `in_package` to a query chain.
63
+
64
+ `statistics` returns a hash of counts and model metrics.
65
+ The synthetic `ModelRoot` contributes to package counts.
66
+ See link:{site-baseurl}/tutorials/querying-models/[Searching and Querying Models]
67
+ for a complete runnable example.
@@ -0,0 +1,72 @@
1
+ ---
2
+ permalink: /references/cli/commands/
3
+ title: Command-Line Compatibility
4
+ parent: Reference
5
+ ---
6
+ = Command-Line Compatibility
7
+
8
+ The LutaML family has been split into separate gems. Historical examples using
9
+ `lutaml uml ...` are not a command reference for the current umbrella package.
10
+ In `lutaml-uml` 1.0.3, the packaged `lutaml` executable requires
11
+ `lutaml/cli`, but that implementation is absent from the gem. The umbrella
12
+ checkout does not supply it either. Use the Ruby APIs below for these workflows.
13
+
14
+ Do not interpret a command name in an older tutorial as evidence that the
15
+ corresponding executable is available in your installed version.
16
+
17
+ [[build]]
18
+ == Build a package
19
+
20
+ Use `repository.export_to_package("model.lur")` after constructing a UML
21
+ repository. The link:{site-baseurl}/tutorials/first-lur-package/[package tutorial]
22
+ has a complete runnable script, including current component initialization.
23
+
24
+ [[search]]
25
+ == Search
26
+
27
+ Use `repository.search("Building", types: [:class])`. Read the grouped results
28
+ and `:total` from the returned hash. For object filtering, use the
29
+ link:{site-baseurl}/tutorials/querying-models/[query DSL].
30
+
31
+ [[export]]
32
+ == Export model data
33
+
34
+ `repository.document.to_yaml` serializes the typed UML document to YAML.
35
+ Write that string with `File.write("model.yaml", ...)` when you need a plain
36
+ model file. Use `export_to_package` when you also need repository metadata
37
+ and indexes in a LUR archive.
38
+
39
+ [[ls]]
40
+ == List elements
41
+
42
+ Use `repository.list_packages("ModelRoot", recursive: true)` for package objects
43
+ or `repository.classes_in_package(path, recursive: true)` for classifiers.
44
+ These are Ruby return values; callers choose the text or table format.
45
+
46
+ [[tree]]
47
+ == Inspect the hierarchy
48
+
49
+ `repository.package_tree("ModelRoot", max_depth: 3)` returns a nested hierarchy.
50
+ It does not print a terminal tree by itself. Use the returned structure in your
51
+ own presentation, or generate a model browser.
52
+
53
+ [[stats]]
54
+ == Read statistics
55
+
56
+ `repository.statistics` returns a hash, including `:total_packages`,
57
+ `:total_classes`, and `:total_diagrams`. Counts include the synthetic root
58
+ package. Rebuild the repository if you change its underlying document.
59
+
60
+ [[docs]]
61
+ == Generate documentation
62
+
63
+ Use `Lutaml::UmlRepository::StaticSite.generate(repository, output: "browser.html")`.
64
+ See link:{site-baseurl}/tutorials/documentation-site/[Creating a Documentation Site]
65
+ for output modes and local inspection.
66
+
67
+ [[serve]]
68
+ == Serve generated files
69
+
70
+ The static output can be served by an ordinary HTTP server. For example,
71
+ `python3 -m http.server 8000` serves the current directory when Python 3 is
72
+ available. Publishing and server configuration are separate from model generation.
@@ -711,6 +711,6 @@ conn_style = resolver.resolve_connector_style(connector, diagram_link)
711
711
 
712
712
  == See Also
713
713
 
714
- * link:diagram-generation[Diagram Generation Guide]
715
- * link:../README[LutaML README]
716
- * link:../config/diagram_styles.yml[Default Configuration File]
714
+ * link:{site-baseurl}/guides/diagram-generation/[Diagram Generation Guide]
715
+ * link:https://github.com/lutaml/lutaml/blob/main/README.md[LutaML README]
716
+ * link:{site-baseurl}/references/configuration/diagram-styles/#configuration-file-format[Configuration File Format]
@@ -1,4 +1,5 @@
1
1
  ---
2
+ permalink: /references/configuration/
2
3
  title: Configuration
3
4
  parent: Reference
4
5
  nav_order: 4
@@ -11,7 +12,7 @@ Complete configuration schemas and reference documentation for LutaML's various
11
12
 
12
13
  == Available Configuration References
13
14
 
14
- === link:diagram-styles[Diagram Styling Configuration]
15
+ === link:{site-baseurl}/references/configuration/diagram-styles/[Diagram Styling Configuration]
15
16
 
16
17
  Complete YAML schema reference for configuring diagram generation with EA-style rendering.
17
18
 
@@ -24,7 +25,7 @@ Complete YAML schema reference for configuring diagram generation with EA-style
24
25
  * Font and color configuration
25
26
  * Box styling options
26
27
 
27
- === link:package-metadata[Package Metadata Configuration]
28
+ === link:{site-baseurl}/references/configuration/package-metadata/[Package Metadata Configuration]
28
29
 
29
30
  YAML configuration for package metadata including XML namespaces and schema locations.
30
31
 
@@ -48,5 +49,5 @@ LutaML searches for configuration files in these locations:
48
49
 
49
50
  == Related Documentation
50
51
 
51
- * link:../../guides[Guides] - How to use these configurations
52
- * link:../../tutorials[Tutorials] - Step-by-step configuration examples
52
+ * link:{site-baseurl}/guides/[Guides] - How to use these configurations
53
+ * link:{site-baseurl}/tutorials/[Tutorials] - Step-by-step configuration examples
@@ -407,10 +407,10 @@ bundle exec rspec spec/lutaml/uml_repository/package_metadata_spec.rb
407
407
 
408
408
  == Example Configuration
409
409
 
410
- See link:../config/package_metadata.example.yml[config/package_metadata.example.yml] for a complete example configuration file with detailed comments.
410
+ See link:https://github.com/lutaml/lutaml-uml/blob/main/config/package_metadata.example.yml[config/package_metadata.example.yml] for a complete example configuration file with detailed comments.
411
411
 
412
412
  == See Also
413
413
 
414
- * link:README[LutaML README] - Main documentation
415
- * link:diagram_generation[Diagram Generation] - Diagram styling integration
416
- * link:../lib/lutaml/uml_repository/package_metadata.rb[PackageMetadata source] - Implementation
414
+ * link:https://github.com/lutaml/lutaml/blob/main/README.md[LutaML README] - Main documentation
415
+ * link:{site-baseurl}/guides/diagram-generation/[Diagram Generation] - Diagram styling integration
416
+ * link:https://github.com/lutaml/lutaml-uml/blob/main/lib/lutaml/uml_repository/package_metadata.rb[PackageMetadata source] - Implementation
@@ -1,4 +1,5 @@
1
1
  ---
2
+ permalink: /references/formats/
2
3
  title: File Formats
3
4
  parent: Reference
4
5
  nav_order: 3
@@ -11,7 +12,7 @@ Complete specifications for all file formats supported by LutaML.
11
12
 
12
13
  == Available Format Specifications
13
14
 
14
- === link:qea-structure[QEA File Format]
15
+ === link:{site-baseurl}/references/formats/qea-structure/[QEA File Format]
15
16
 
16
17
  Enterprise Architect's native SQLite database format specification.
17
18
 
@@ -23,7 +24,7 @@ Enterprise Architect's native SQLite database format specification.
23
24
  * Performance characteristics
24
25
  * Configuration and usage
25
26
 
26
- === link:lutaml-syntax[LutaML Syntax Reference]
27
+ === link:{site-baseurl}/references/formats/lutaml-syntax/[LutaML Syntax Reference]
27
28
 
28
29
  Complete syntax reference for LutaML's native modeling DSL.
29
30
 
@@ -38,5 +39,5 @@ Complete syntax reference for LutaML's native modeling DSL.
38
39
 
39
40
  == Related Documentation
40
41
 
41
- * link:../../guides/parsing[Parsing Guides] - How to parse these formats
42
- * link:../../pages[Core Topics] - Understanding model structures
42
+ * link:{site-baseurl}/guides/parsing/[Parsing Guides] - How to parse these formats
43
+ * link:{site-baseurl}/core/[Core Topics] - Understanding model structures
@@ -0,0 +1,39 @@
1
+ ---
2
+ permalink: /references/formats/lur-format/
3
+ title: LUR Package Format
4
+ parent: Reference
5
+ ---
6
+ = LUR Package Format
7
+
8
+ A `.lur` file is a ZIP archive produced by the UML repository exporter.
9
+ It packages a typed UML document, lookup indexes, and descriptive metadata.
10
+ Use the repository loader and exporter instead of constructing an archive by hand.
11
+
12
+ == Archive entries
13
+
14
+ [cols="1,2",options="header"]
15
+ |===
16
+ |Entry |Contents
17
+ |`metadata.yaml` |Package metadata, serialization format, timestamps, component version, and statistics.
18
+ |`repository.yaml` |The serialized `Lutaml::Uml::Document`.
19
+ |`indexes/all.yaml` |The repository's lookup indexes.
20
+ |`index_tree.yaml` |A searchable package/class summary.
21
+ |`statistics.yaml` |Repository statistics.
22
+ |===
23
+
24
+ These names describe the YAML package writer in `lutaml-uml` 1.0.3.
25
+ Do not assume that an arbitrary ZIP or renamed XMI file is a valid LUR package.
26
+
27
+ == Read and write
28
+
29
+ Call `Repository.from_package(path)` to load a package and
30
+ `repository.export_to_package(path)` to export it.
31
+ The exporter defaults to YAML document serialization and compression level 6.
32
+ It accepts package metadata through its options; see
33
+ link:{site-baseurl}/references/configuration/package-metadata/[Package Metadata].
34
+ The link:{site-baseurl}/tutorials/first-lur-package/[package tutorial] includes
35
+ the version require needed by the current exporter and verifies a full round trip.
36
+
37
+ The loader reports absent files with `ArgumentError` and reports invalid ZIP
38
+ or deserialization failures as load errors. Keep your source model and lockfile
39
+ so that you can regenerate the package when its model or dependency versions change.
@@ -1344,10 +1344,10 @@ Connection pooling:: Reuses database connections
1344
1344
 
1345
1345
  === Documentation
1346
1346
 
1347
- * link:QEA_DATABASE_TABLE_ANALYSIS.md[Detailed table analysis]
1348
- * link:../README[LutaML main documentation]
1349
- * link:DIAGRAM_SUPPORT_IMPLEMENTATION.md[Diagram implementation details]
1350
- * link:OBJECT_PROPERTIES_IMPLEMENTATION.md[Object properties implementation]
1347
+ * <<implemented-tables,Detailed table analysis>>
1348
+ * link:https://github.com/lutaml/lutaml/blob/main/README.md[LutaML main documentation]
1349
+ * <<diagram-tables,Diagram table details>>
1350
+ * <<t_objectproperties-object-properties,Object property fields>>
1351
1351
 
1352
1352
  === Source code
1353
1353
 
@@ -1,4 +1,5 @@
1
1
  = Reference
2
+ :page-permalink: /references/
2
3
  :nav_order: 4
3
4
  :has_children: true
4
5
 
@@ -8,26 +9,26 @@ This section provides detailed technical specifications, API documentation, and
8
9
 
9
10
  == Command-Line Interface
10
11
 
11
- === link:cli/commands[Complete Command Reference]
12
+ === link:{site-baseurl}/references/cli/commands/[Complete Command Reference]
12
13
 
13
- Comprehensive reference for all CLI commands, options, and arguments.
14
+ Current executable compatibility and Ruby replacements for the historical UML commands.
14
15
 
15
- === Individual Commands
16
+ === Historical Commands and Ruby Replacements
16
17
 
17
- * link:cli/build[`lutaml uml build`] - Build LUR packages
18
- * link:cli/search[`lutaml uml search`] - Search models
19
- * link:cli/export[`lutaml uml export`] - Export data
20
- * link:cli/ls[`lutaml uml ls`] - List elements
21
- * link:cli/tree[`lutaml uml tree`] - Show hierarchy
22
- * link:cli/stats[`lutaml uml stats`] - Statistics
23
- * link:cli/docs[`lutaml uml docs`] - Generate docs
24
- * link:cli/serve[`lutaml uml serve`] - Start server
18
+ * link:{site-baseurl}/references/cli/commands/#build[`lutaml uml build`] - Build LUR packages
19
+ * link:{site-baseurl}/references/cli/commands/#search[`lutaml uml search`] - Search models
20
+ * link:{site-baseurl}/references/cli/commands/#export[`lutaml uml export`] - Export data
21
+ * link:{site-baseurl}/references/cli/commands/#ls[`lutaml uml ls`] - List elements
22
+ * link:{site-baseurl}/references/cli/commands/#tree[`lutaml uml tree`] - Show hierarchy
23
+ * link:{site-baseurl}/references/cli/commands/#stats[`lutaml uml stats`] - Statistics
24
+ * link:{site-baseurl}/references/cli/commands/#docs[`lutaml uml docs`] - Generate docs
25
+ * link:{site-baseurl}/references/cli/commands/#serve[`lutaml uml serve`] - Start server
25
26
 
26
27
  == API Documentation
27
28
 
28
29
  === Core APIs
29
30
 
30
- ==== link:api/repository[Repository API]
31
+ ==== link:{site-baseurl}/references/api/repository/[Repository API]
31
32
 
32
33
  Complete API reference for `Lutaml::UmlRepository::Repository` class.
33
34
 
@@ -38,9 +39,9 @@ Complete API reference for `Lutaml::UmlRepository::Repository` class.
38
39
  * Index management
39
40
  * Statistics calculation
40
41
 
41
- ==== link:api/parsers[Parser APIs]
42
+ ==== link:{site-baseurl}/references/api/parsers/[Parser APIs]
42
43
 
43
- Reference for all parser interfaces and implementations.
44
+ Entry points and result types for LML, EXPRESS, LUR, and external importers.
44
45
 
45
46
  **Topics:**
46
47
 
@@ -49,7 +50,7 @@ Reference for all parser interfaces and implementations.
49
50
  * Parser options
50
51
  * Error handling
51
52
 
52
- ==== link:api/presenters[Presenter APIs]
53
+ ==== link:{site-baseurl}/references/api/presenters/[Presenter APIs]
53
54
 
54
55
  Documentation for element presentation and formatting.
55
56
 
@@ -68,14 +69,14 @@ Complete reference for the query DSL syntax and methods.
68
69
 
69
70
  * `Lutaml::Uml::Document`
70
71
  * `Lutaml::Uml::Package`
71
- * `Lutaml::Uml::Class`
72
- * `Lutaml::Uml::Attribute`
72
+ * `Lutaml::Uml::UmlClass`
73
+ * `Lutaml::Uml::TopElementAttribute`
73
74
  * `Lutaml::Uml::Association`
74
75
  * `Lutaml::Uml::Diagram`
75
76
 
76
77
  == File Formats
77
78
 
78
- === link:formats/qea-structure[QEA File Format]
79
+ === link:{site-baseurl}/references/formats/qea-structure/[QEA File Format]
79
80
 
80
81
  Complete specification of Enterprise Architect's QEA (SQLite) database format.
81
82
 
@@ -86,7 +87,7 @@ Complete specification of Enterprise Architect's QEA (SQLite) database format.
86
87
  * Data types
87
88
  * Supported EA versions
88
89
 
89
- === link:formats/lur-format[LUR Package Format]
90
+ === link:{site-baseurl}/references/formats/lur-format/[LUR Package Format]
90
91
 
91
92
  Specification of LutaML's compressed repository format.
92
93
 
@@ -97,7 +98,7 @@ Specification of LutaML's compressed repository format.
97
98
  * Versioning
98
99
  * Metadata
99
100
 
100
- === link:formats/lutaml-syntax[LutaML Syntax]
101
+ === link:{site-baseurl}/references/formats/lutaml-syntax/[LutaML Syntax]
101
102
 
102
103
  Complete syntax reference for LutaML's native DSL.
103
104
 
@@ -118,7 +119,7 @@ ISO 10303-11 EXPRESS schema support via Expressir.
118
119
 
119
120
  == Configuration
120
121
 
121
- === link:configuration/diagram-styles[Diagram Styling Configuration]
122
+ === link:{site-baseurl}/references/configuration/diagram-styles/[Diagram Styling Configuration]
122
123
 
123
124
  Complete YAML schema for diagram style configuration.
124
125
 
@@ -129,7 +130,7 @@ Complete YAML schema for diagram style configuration.
129
130
  * Connector types
130
131
  * Priority rules
131
132
 
132
- === link:configuration/package-metadata[Package Metadata Configuration]
133
+ === link:{site-baseurl}/references/configuration/package-metadata/[Package Metadata Configuration]
133
134
 
134
135
  YAML schema for package metadata including XML namespaces.
135
136
 
@@ -192,6 +193,6 @@ Operating system and platform compatibility.
192
193
 
193
194
  == Related Sections
194
195
 
195
- * link:../pages[Core Topics] - Fundamental concepts
196
- * link:../tutorials[Tutorials] - Step-by-step learning
197
- * link:../guides[Guides] - Task-oriented documentation
196
+ * link:{site-baseurl}/core/[Core Topics] - Fundamental concepts
197
+ * link:{site-baseurl}/tutorials/[Tutorials] - Step-by-step learning
198
+ * link:{site-baseurl}/guides/[Guides] - Task-oriented documentation
@@ -0,0 +1,47 @@
1
+ ---
2
+ permalink: /tutorials/documentation-site/
3
+ title: Creating a Documentation Site
4
+ parent: Tutorials
5
+ nav_order: 4
6
+ ---
7
+ = Creating a Documentation Site
8
+
9
+ Generate a model browser from the small repository in
10
+ link:{site-baseurl}/tutorials/getting-started/[Getting Started].
11
+ This uses the Ruby static-site API in `lutaml-uml`, rather than the historical
12
+ `lutaml uml build-spa` command.
13
+
14
+ == Generate the browser
15
+
16
+ Save this as `build_site.rb` beside `city_model.rb`:
17
+
18
+ [source,ruby]
19
+ ----
20
+ include::../examples/build_site.rb[]
21
+ ----
22
+
23
+ Run `bundle exec ruby build_site.rb browser.html` with a new output filename.
24
+ The script verifies that the generator wrote a nonempty HTML file.
25
+ It explicitly loads `lutaml/uml/version`, which the current generator uses
26
+ when constructing its metadata.
27
+
28
+ == Serve and inspect
29
+
30
+ Serve the output directory with an HTTP server. For example, if Python 3 is
31
+ available, run `python3 -m http.server 8000` there, then open
32
+ `http://localhost:8000/browser.html`. Check that the City package and Building
33
+ class appear, and search for Building.
34
+
35
+ Generating a file does not publish a website. Upload the generated output to
36
+ your chosen static host when you are ready to publish it.
37
+
38
+ == Use an existing model
39
+
40
+ Load a LUR package with `Repository.from_package` and pass the resulting
41
+ repository to `StaticSite.generate`. Set `mode: :multi_file` and an output
42
+ directory to produce separate assets instead of a single HTML file.
43
+ Use `config_path:` to select a static-site configuration file; diagram styling
44
+ and package metadata are separate configuration concerns.
45
+
46
+ The example has no stored EA diagrams. Generating a model browser does not
47
+ prove that QEA import or EA SVG rendering is available in the installed bundle.
@@ -0,0 +1,45 @@
1
+ ---
2
+ permalink: /tutorials/first-lur-package/
3
+ title: Building Your First LUR Package
4
+ parent: Tutorials
5
+ nav_order: 2
6
+ ---
7
+ = Building Your First LUR Package
8
+
9
+ Save the model from link:{site-baseurl}/tutorials/getting-started/[Getting Started]
10
+ as a `.lur` file and verify that its class survives a reload.
11
+
12
+ == Export and reload
13
+
14
+ Keep `city_model.rb` in the same directory as this script, named `build_package.rb`:
15
+
16
+ [source,ruby]
17
+ ----
18
+ include::../examples/build_package.rb[]
19
+ ----
20
+
21
+ Run `bundle exec ruby build_package.rb city.lur` with a new output filename.
22
+ It writes `city.lur`, reloads it, and prints `Building`.
23
+ The explicit version require supplies the constant used by the exporter in
24
+ `lutaml-uml` 1.0.3; the umbrella's version is a separate constant.
25
+
26
+ == Inspect the result
27
+
28
+ A LUR package is a ZIP archive. Inspect its entry names with a ZIP viewer:
29
+ `metadata.yaml`, `repository.yaml`, `indexes/all.yaml`, `index_tree.yaml`,
30
+ and `statistics.yaml` describe the model and its lookup data.
31
+ See link:{site-baseurl}/references/formats/lur-format/[LUR Package Format]
32
+ for the loading contract.
33
+
34
+ `Repository.from_file("city.lur")` is another way to load the package.
35
+ It does not parse QEA or XMI files. Parse those formats with the appropriate
36
+ provider first, then pass its UML document to `Repository.from_document`.
37
+
38
+ == Maintain the package
39
+
40
+ Keep the original model file and the bundle lockfile alongside generated
41
+ artifacts. Rebuild a package when its source changes. Do not use the existence
42
+ of an old `.lur` file as proof that it represents the latest source model.
43
+
44
+ Next, link:{site-baseurl}/tutorials/querying-models/[search and query the model]
45
+ or link:{site-baseurl}/tutorials/documentation-site/[generate a documentation site].
@@ -0,0 +1,42 @@
1
+ ---
2
+ permalink: /tutorials/generating-diagrams/
3
+ title: Generating an LML Diagram
4
+ parent: Tutorials
5
+ nav_order: 3
6
+ ---
7
+ = Generating an LML Diagram
8
+
9
+ Render a small textual LML model as SVG. This tutorial uses Graphviz layout;
10
+ it does not reconstruct an Enterprise Architect diagram's saved coordinates.
11
+
12
+ == Prerequisites
13
+
14
+ Install the `lutaml` gem in your bundle. The Graphviz `dot` executable must
15
+ already be available on `PATH`; check with `dot -V`.
16
+ The Ruby formatter invokes that executable to perform layout and rendering.
17
+
18
+ == Render the model
19
+
20
+ Save this as `render_diagram.rb`:
21
+
22
+ [source,ruby]
23
+ ----
24
+ include::../examples/render_diagram.rb[]
25
+ ----
26
+
27
+ Run `bundle exec ruby render_diagram.rb city.svg` with a new output filename.
28
+ The script rejects output without an SVG root element. Open `city.svg` in a
29
+ browser and check that the Building class appears.
30
+
31
+ == Change the output
32
+
33
+ Set `formatter.type = :png` and write to `city.png` for a raster image, or
34
+ `:pdf` and `city.pdf` for PDF. The requested Graphviz format must be supported
35
+ by your local Graphviz installation. Replace the SVG-specific output check
36
+ when selecting another format. Changing the filename alone does not
37
+ change the formatter's output type.
38
+
39
+ For model browser generation, see
40
+ link:{site-baseurl}/tutorials/documentation-site/[Creating a Documentation Site].
41
+ For the distinction between LML parsing and UML repository models, see
42
+ link:{site-baseurl}/references/api/parsers/[Parser APIs].