lutaml 0.9.43 → 0.10.0

data/docs/README.md

@@ -0,0 +1,252 @@
+# LutaML Documentation
+
+This directory contains the LutaML documentation website built with Jekyll and the just-the-docs theme.
+
+## 🎉 Jekyll Site Structure: READY
+
+The documentation framework is complete and ready for content migration.
+
+## Quick Start
+
+### Local Development
+
+```bash
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+Open http://localhost:4000/lutaml/
+
+### Production Build
+
+```bash
+cd docs
+JEKYLL_ENV=production bundle exec jekyll build
+```
+
+Output in `_site/` directory.
+
+## Site Structure
+
+```
+docs/
+├── index.adoc                  # Homepage ✅
+├── _config.yml                 # Jekyll configuration ✅
+├── Gemfile                     # Dependencies ✅
+├── lychee.toml                # Link checker config ✅
+│
+├── _pages/                     # Core Topics collection ✅
+│   ├── index.adoc             # Collection overview
+│   └── concepts/              # Concepts subdirectory
+│
+├── _tutorials/                 # Tutorials collection ✅
+│   └── index.adoc             # Collection overview
+│
+├── _guides/                    # Guides collection ✅
+│   ├── index.adoc             # Collection overview
+│   └── parsing/               # Parsing guides subdirectory
+│
+├── _references/                # Reference collection ✅
+│   ├── index.adoc             # Collection overview
+│   ├── cli/                   # CLI reference
+│   ├── api/                   # API reference
+│   ├── formats/               # Format specifications
+│   └── configuration/         # Configuration schemas
+│
+└── .github/workflows/          # CI/CD ✅
+    ├── docs.yml               # Build and deploy
+    └── links.yml              # Link checking
+```
+
+## Documentation Collections
+
+### 1. Core Topics (_pages/)
+
+Fundamental concepts and essential information.
+
+**Status**: Skeleton ready, content needs migration
+
+### 2. Tutorials (_tutorials/)
+
+Step-by-step learning paths with complete workflows.
+
+**Status**: Overview ready, tutorials need creation
+
+### 3. Guides (_guides/)
+
+Task-oriented how-to documentation.
+
+**Status**: Overview ready, guides need migration
+
+### 4. Reference (_references/)
+
+Detailed technical specifications and API docs.
+
+**Status**: Structure ready, content needs migration
+
+## Next Steps
+
+See [`MIGRATION_GUIDE.md`](MIGRATION_GUIDE.md) for detailed instructions on:
+
+1. Content migration from existing docs
+2. Front matter requirements
+3. Link updating procedures
+4. Testing checklist
+
+See [`REFACTOR_PLAN.md`](REFACTOR_PLAN.md) for complete categorization and mapping.
+
+## Contributing
+
+### Adding a New Page
+
+1. Create file in appropriate collection directory
+2. Add YAML front matter:
+   ```yaml
+   ---
+   title: Page Title
+   parent: Parent Page Title
+   nav_order: 1
+   ---
+   ```
+3. Write content in AsciiDoc format
+4. Test locally: `bundle exec jekyll serve`
+5. Submit pull request
+
+### Updating Existing Pages
+
+1. Edit the `.adoc` file
+2. Update cross-references if needed
+3. Test build locally
+4. Submit pull request
+
+## GitHub Actions
+
+### Build and Deploy (docs.yml)
+
+Automatically builds and deploys on push to main.
+
+**Triggers**: Push to main, pull requests, manual dispatch
+
+### Link Checking (links.yml)
+
+Validates all links in documentation.
+
+**Triggers**: Push to main, pull requests, weekly schedule
+
+## Link Syntax
+
+Use AsciiDoc format for all internal links:
+
+```adoc
+link:relative/path.adoc[Link Text]
+link:../_pages/installation.adoc[Installation Guide]
+```
+
+## Front Matter Reference
+
+### Top-level page:
+```yaml
+---
+title: Page Title
+nav_order: 1
+---
+```
+
+### Child page:
+```yaml
+---
+title: Child Page
+parent: Parent Page Title
+nav_order: 2
+---
+```
+
+### Grandchild:
+```yaml
+---
+title: Grandchild
+parent: Child Page Title
+grand_parent: Parent Page Title
+nav_order: 1
+---
+```
+
+## Configuration
+
+### Site Settings (_config.yml)
+
+- Title: LutaML Documentation
+- Base URL: /lutaml
+- Theme: just-the-docs 0.7.0
+- 4 collections configured
+- Search enabled
+- Link checking enabled
+
+### Dependencies (Gemfile)
+
+- jekyll (~> 4.3)
+- just-the-docs (0.7.0)
+- jekyll-asciidoc
+- jekyll-seo-tag
+- jekyll-sitemap
+
+### Link Checker (lychee.toml)
+
+- Caching enabled
+- Follows redirects
+- Excludes examples and localhost
+- Retry logic for rate limits
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Serve locally with live reload
+bundle exec jekyll serve --livereload
+
+# Build for production
+JEKYLL_ENV=production bundle exec jekyll build
+
+# Check links
+bundle exec jekyll build
+lychee --config lychee.toml '_site/**/*.html'
+
+# Clean build artifacts
+bundle exec jekyll clean
+```
+
+## Troubleshooting
+
+### "Liquid Exception: Included file '_includes/head.html' not found"
+
+Install theme: `bundle install`
+
+### Links showing as [link text](broken_path)
+
+Use AsciiDoc syntax: `link:path.adoc[Text]`
+
+### Navigation not showing pages
+
+Check front matter `parent` matches parent `title` exactly.
+
+### Search not working
+
+Rebuild site to regenerate search index.
+
+## Resources
+
+- **Jekyll**: https://jekyllrb.com/docs/
+- **Just the Docs**: https://just-the-docs.github.io/just-the-docs/
+- **AsciiDoc**: https://docs.asciidoctor.org/asciidoc/latest/
+- **Migration Guide**: [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)
+- **Refactor Plan**: [REFACTOR_PLAN.md](REFACTOR_PLAN.md)
+
+## Status
+
+**Infrastructure**: ✅ Complete  
+**Content Migration**: 📝 In Progress  
+**Testing**: ⏳ Pending  
+**Deployment**: 🚀 Ready

data/docs/REFACTOR_PLAN.md

@@ -0,0 +1,214 @@
+# Documentation Refactoring Plan
+
+## Goal
+Refactor LutaML documentation into a Jekyll-based 4-collection structure following industry best practices.
+
+## Current State Analysis
+
+### User Documentation (Keep & Restructure)
+1. **README.adoc** (2015 lines) - Comprehensive guide, needs to be split
+2. **diagram-generation.adoc** - Guide for EA diagram generation
+3. **diagram-configuration.adoc** - Configuration reference
+4. **lutaml-uml.adoc** - UML language guide
+5. **lutaml-express.adoc** - EXPRESS parsing
+6. **lutaml-xmi.adoc** - XMI parsing
+7. **lutaml_syntax.adoc** - Syntax reference
+8. **ea_qea_structure.adoc** - QEA format specification
+9. **package_metadata.adoc** - Metadata configuration
+
+### Internal Documentation (Archive)
+- CLI_THOR_ARCHITECTURE.md
+- COMPREHENSIVE_VALIDATION_PLAN.md
+- CONTINUATION_PROMPT.txt
+- DIAGRAM_SUPPORT_IMPLEMENTATION.md
+- IMPLEMENTATION_PLAN.md
+- NOTE_OBJECT_ARCHITECTURE.md
+- QEA_PARSER_IMPLEMENTATION_STATUS.md
+- SPA_CONTINUATION_PLAN.md
+- svg_comparison_results.md
+- TWO_PHASE_VALIDATION_IMPLEMENTATION.md
+- VALIDATION_ARCHITECTURE_REDESIGN.md
+- architecture/SPA_ARCHITECTURE.md
+- features/SPA_BROWSER.md
+
+## Target Structure
+
+### Collection 1: Core Topics (_pages/)
+**Purpose**: Fundamental concepts and essential information
+
+- `index.adoc` - Core Topics Overview
+- `overview.adoc` - What is LutaML
+- `installation.adoc` - Installation guide
+- `architecture.adoc` - System architecture
+- `concepts/` - Core concepts directory
+  - `qea-parsing.adoc` - QEA direct parsing
+  - `lur-format.adoc` - LUR package format
+  - `uml-models.adoc` - UML model structure
+  - `diagram-generation.adoc` - Diagram generation overview
+
+### Collection 2: Tutorials (_tutorials/)
+**Purpose**: Step-by-step learning paths
+
+- `index.adoc` - Tutorials Overview
+- `getting-started.adoc` - Quick start tutorial
+- `first-lur-package.adoc` - Building your first LUR
+- `generating-diagrams.adoc` - Creating diagrams
+- `documentation-site.adoc` - Building a docs site
+- `querying-models.adoc` - Searching and querying
+
+### Collection 3: Guides (_guides/)
+**Purpose**: Task-oriented how-to documentation
+
+- `index.adoc` - Guides Overview
+- `cli-usage.adoc` - CLI usage guide
+- `diagram-configuration.adoc` - Configuring diagrams
+- `package-metadata.adoc` - Package metadata setup
+- `repository-management.adoc` - Managing repositories
+- `parsing/` - Parsing guides
+  - `qea-parsing.adoc` - QEA parsing guide
+  - `xmi-parsing.adoc` - XMI parsing guide
+  - `express-parsing.adoc` - EXPRESS parsing guide
+
+### Collection 4: References (_references/)
+**Purpose**: Detailed technical specifications
+
+- `index.adoc` - References Overview
+- `cli/` - CLI reference
+  - `commands.adoc` - Complete command reference
+  - `build.adoc` - Build command
+  - `search.adoc` - Search command
+  - `export.adoc` - Export command
+- `api/` - API reference
+  - `repository.adoc` - Repository API
+  - `parsers.adoc` - Parser APIs
+  - `presenters.adoc` - Presenter APIs
+- `formats/` - Format specifications
+  - `qea-structure.adoc` - QEA file format
+  - `lur-format.adoc` - LUR package format
+  - `lutaml-syntax.adoc` - LutaML syntax
+- `configuration/` - Configuration schemas
+  - `diagram-styles.adoc` - Diagram styling config
+  - `package-metadata.adoc` - Package metadata config
+
+## Implementation Steps
+
+### Phase 1: Setup (Priority 1)
+- [x] Create refactoring plan
+- [ ] Create directory structure
+- [ ] Setup Jekyll _config.yml
+- [ ] Create main index.adoc
+- [ ] Create collection overview pages
+
+### Phase 2: Content Migration (Priority 1)
+- [ ] Migrate core topics to _pages/
+- [ ] Create tutorials from README examples
+- [ ] Convert guides
+- [ ] Move references
+
+### Phase 3: CI/CD (Priority 2)
+- [ ] Add GitHub Actions workflow
+- [ ] Setup link checking
+- [ ] Create lychee.toml
+
+### Phase 4: Cleanup (Priority 2)
+- [ ] Archive internal docs to old-docs/
+- [ ] Update cross-references
+- [ ] Fix all internal links
+
+### Phase 5: Testing (Priority 3)
+- [ ] Test Jekyll build
+- [ ] Verify all links
+- [ ] Check mobile responsiveness
+
+## Content Mapping
+
+### From README.adoc
+
+**To _pages/:**
+- Overview section → overview.adoc
+- Installation → installation.adoc
+- Architecture intro → architecture.adoc
+
+**To _tutorials/:**
+- Quick start → getting-started.adoc
+- Basic usage examples → first-lur-package.adoc
+
+**To _guides/:**
+- CLI command usage → cli-usage.adoc
+- Interactive features → guides/
+
+**To _references/:**
+- CLI commands reference → references/cli/commands.adoc
+- API reference → references/api/
+
+### Diagram Documentation
+
+**diagram-generation.adoc → Split:**
+- Overview/intro → _pages/concepts/diagram-generation.adoc
+- Configuration basics → _tutorials/generating-diagrams.adoc
+- Advanced configuration → _guides/diagram-configuration.adoc
+
+**diagram-configuration.adoc:**
+- All content → _references/configuration/diagram-styles.adoc
+
+### Format Documentation
+
+**ea_qea_structure.adoc:**
+- All content → _references/formats/qea-structure.adoc
+
+**lutaml_syntax.adoc:**
+- All content → _references/formats/lutaml-syntax.adoc
+
+**package_metadata.adoc:**
+- Concept/overview → _pages/concepts/ (brief)
+- Setup guide → _guides/package-metadata.adoc
+- Full reference → _references/configuration/package-metadata.adoc
+
+## Front Matter Template
+
+Every page needs YAML front matter:
+
+```yaml
+---
+title: Page Title
+parent: Parent Page Title (if nested)
+nav_order: 1
+---
+```
+
+## Principles
+
+1. **Onion Structure**: Information revealed incrementally
+2. **3-Click Rule**: Any topic reachable within 3 clicks
+3. **Content First**: Focus on user needs, not structure
+4. **MECE**: Mutually Exclusive, Collectively Exhaustive
+5. **No Orphans**: Every page linked from somewhere
+
+## Navigation Order
+
+Set `nav_order` to create logical flow:
+- Core concepts: 1-10
+- Getting started: 11-20
+- Tutorials: 21-30
+- Guides: 31-40
+- References: 41-50
+
+## Cross-References
+
+Use relative links:
+```adoc
+See link:../guides/cli-usage.adoc[CLI Usage Guide]
+```
+
+## Testing Checklist
+
+- [ ] All pages have front matter
+- [ ] All links work
+- [ ] Navigation is logical
+- [ ] Mobile responsive
+- [ ] Search works
+- [ ] Dark/light theme works
+- [ ] No 404s
+- [ ] Images load
+- [ ] Code blocks render
+- [ ] Tables format correctly

data/docs/_config.yml

@@ -0,0 +1,144 @@
+# Site settings
+title: LutaML Ruby
+description: >-
+  Universal Ruby library and CLI for accessing, parsing, and manipulating data models
+  across multiple modeling languages including UML, EXPRESS, and Enterprise Architect formats
+baseurl: "/lutaml"
+url: "https://www.lutaml.org"
+
+# Theme
+theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.10.1
+
+# Color scheme
+color_scheme: light
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Heading anchors
+heading_anchors: true
+
+# Aux links for the upper right navigation
+aux_links:
+  "GitHub":
+    - "https://github.com/lutaml/lutaml"
+  "RubyGems":
+    - "https://rubygems.org/gems/lutaml"
+
+# Makes Aux links open in a new tab
+aux_links_new_tab: true
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Footer content
+footer_content: >-
+  Copyright © 2025 Ribose. Distributed by a
+  <a href="https://github.com/lutaml/lutaml/blob/main/LICENSE">BSD-3-Clause license</a>.
+
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Navigation structure
+nav_sort: order
+
+# Collections for organizing content
+collections:
+  pages:
+    permalink: "/:path/"
+    output: true
+  tutorials:
+    permalink: "/:collection/:path/"
+    output: true
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+  references:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Core Topics
+      nav_fold: false
+    tutorials:
+      name: Tutorials
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    references:
+      name: Reference
+      nav_fold: true
+
+# Plugins
+plugins:
+  - jekyll-asciidoc
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# AsciiDoc configuration
+asciidoc: {}
+asciidoctor:
+  attributes:
+    - source-highlighter=rouge
+    - rouge-style=github
+    - icons=font
+    - sectanchors=true
+    - idprefix=
+    - idseparator=-
+    - experimental=true
+    - xrefstyle=short
+
+# Include AsciiDoc files
+include:
+  - "*.adoc"
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - _site
+  - node_modules
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+  - Rakefile
+  - "*.md"
+  - architecture/
+  - features/
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red