xseed 1.0.0

data/README.adoc

@@ -0,0 +1,386 @@
+= Xseed: Ruby XSD Documentation Generator
+
+image:https://img.shields.io/gem/v/xseed.svg[RubyGems Version, link=https://rubygems.org/gems/xseed]
+image:https://img.shields.io/github/license/metanorma/xseed.svg[License, link=https://github.com/metanorma/xseed/blob/main/LICENSE.adoc]
+image:https://github.com/metanorma/xseed/actions/workflows/test.yml/badge.svg["Build", link="https://github.com/metanorma/xseed/actions/workflows/test.yml"]
+image:https://img.shields.io/badge/parity-100%25-brightgreen[Parity]
+image:https://img.shields.io/badge/coverage-87.63%25-brightgreen[Coverage]
+
+== Purpose
+
+Xseed provides comprehensive XSD documentation generation with a single command:
+
+* **Automatic SVG generation** - When generating HTML, xseed automatically creates SVG diagrams for all elements using the xsdvi gem
+* **HTML documentation** - Complete schema reference with embedded SVG diagrams (XS3P port)
+* **Single-command workflow** - One command generates everything: HTML + all SVG diagrams
+
+== Features
+
+* **Single-command generation** - `xseed html` automatically generates HTML documentation and all SVG diagrams
+* **Integrated SVG diagrams** - Uses xsdvi gem Ruby API to generate diagram for each element
+* **Comprehensive HTML** - Schema properties, component listings, type hierarchies, XML samples
+* <<cli-interface,Professional CLI>> - Thor-based with verbose mode and progress indicators
+* <<performance,High performance>> - Generates complete documentation in milliseconds
+* <<error-handling,Robust error handling>> - Graceful degradation with helpful messages
+* **21 complete features** - All P0, P1, and P2 features implemented
+
+== Quick Start
+
+[source,shell]
+----
+# Install the gem (includes xsdvi for SVG generation)
+gem install xseed
+
+# Generate complete documentation (HTML + all SVG diagrams)
+xseed html schema.xsd -o docs/index.html
+
+# Result:
+#   docs/index.html           (HTML with embedded SVG references)
+#   docs/diagrams/*.svg       (SVG diagram for each element)
+
+# View schema information
+xseed info schema.xsd
+
+# Display help
+xseed help
+----
+
+== Complete Workflow
+
+=== Single-command integrated documentation
+
+**One command does everything** - xseed automatically generates all SVG diagrams when creating HTML:
+
+[source,shell]
+----
+# This single command generates EVERYTHING:
+xseed html schema.xsd -o docs/index.html
+----
+
+**What it generates:**
+
+* `docs/index.html` - Complete HTML documentation
+* `docs/diagrams/*.svg` - SVG diagram for EVERY element (auto-generated using xsdvi)
+* Proper `<object>` tag integration in HTML
+
+**That's it!** No need for separate SVG generation commands.
+
+.Real-world example with UnitsML (54 elements)
+====
+[source,shell]
+----
+$ xseed html unitsml-v1.0.xsd -o output/index.html --title "UnitsML Docs" --verbose
+
+  → Creating HTML generator for: unitsml-v1.0.xsd
+  → HTML generator initialized
+  → Generating HTML documentation...
+    ✓ Complete
+✓ HTML documentation generated: output/index.html
+  → Generation completed in 0.341s
+
+# Generated files:
+#   output/index.html               (752KB HTML)
+#   output/diagrams/Unit.svg        (54 SVG files, one per element)
+#   output/diagrams/Quantity.svg
+#   output/diagrams/Prefix.svg
+#   ... (and 51 more)
+
+$ open output/index.html
+----
+
+The HTML automatically includes all 54 SVG diagrams with proper `<object>` tags.
+====
+</commands>
+* `-o, --output PATH` - Output HTML file path (required)
+* `-t, --title TEXT` - Custom documentation title
+* `-d, --diagrams-dir DIR` - Custom SVG directory name (default: "diagrams")
+* `--css PATH` - External CSS file URL
+* `-v, --verbose` - Show detailed progress
+* `-f, --force` - Overwrite without confirmation
+
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+import@<interface>
+QPushButton{
+    {name}:
+    {instruction}
+}
+/**
+ * Define a QPushButton class
+ * @class {class_name}
+ * @burnsPanel {bool}
+ * @order {number}
+ * @classname {string}
+ * @compName {string}
+ * @instruction {string}
+ * @defaultValues {any}
+ * @interface {any}
+ */
+class ${currentSymbol}(${interface}) {
+:
+//////////////////////////////////////
+private:
+signals:
+/**
+ * Construct a QPushButton with the given panel
+ * @constructor
+ * @return {void}
+ * @param {QObject} parent -
+ * @description Constructor that will be called from Panel
+ */
+${currentSymbol} Sweeper(QWidget* parent) : QPushButton(parent){
+    this->settings.definition$is_GeneratableNewPanel = true;
+    this->settings.definition$is_BurnsPanel = ${classdata.burnsPanel};
+    this->settings.definition$order = ${classdata.order};
+    this->settings.definition.className = "${className}";
+    this->settings.definition.compName = "${classCompName}";
+    this->settings.definition.instructions = "${instruction}";
+    this->settings.definition.defaultValue = varObject${functionSeparator}${className};
+    this->settings.definition.defaults.push_back(varObject(${functionSeparator}"${className}"));
+    this->settings.definition.interface = ${interface};
+    //this->setParent(parent);
+}
+}

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/README.adoc

@@ -0,0 +1,334 @@
+= Xseed Examples
+
+This directory contains comprehensive examples demonstrating various features and usage patterns of the Xseed gem.
+
+== Quick Start
+
+[source,shell]
+----
+# Run simple examples
+ruby examples/simple_generation.rb
+
+# Run advanced examples
+ruby examples/advanced_usage.rb
+----
+
+== Example Files
+
+=== Simple Generation (`simple_generation.rb`)
+
+Demonstrates basic SVG generation workflows:
+
+* **Example 1**: Generate SVG to stdout
+* **Example 2**: Generate SVG to file
+* **Example 3**: Error handling patterns
+* **Example 4**: Schema inspection before generation
+* **Example 5**: Batch processing multiple schemas
+
+[source,shell]
+----
+ruby examples/simple_generation.rb
+----
+
+=== Advanced Usage (`advanced_usage.rb`)
+
+Demonstrates advanced features and patterns:
+
+* **Example 1**: Parser introspection and metadata extraction
+* **Example 2**: Conditional generation based on schema analysis
+* **Example 3**: Custom error handling and logging
+* **Example 4**: Performance monitoring and profiling
+* **Example 5**: Integration with other tools
+
+[source,shell]
+----
+ruby examples/advanced_usage.rb
+----
+
+== Example Schemas
+
+=== person.xsd
+
+A comprehensive example schema demonstrating:
+
+* **Simple types** with restrictions and enumerations
+* **Complex types** with sequences and choices
+* **Nested structures** (Address within Person)
+* **Attributes** (required and optional)
+* **Documentation** annotations throughout
+* **Namespaces** and target namespace usage
+
+This schema serves as a realistic example for testing and demonstration purposes.
+
+== Output
+
+Generated SVG files are saved to `examples/output/`. This directory is created automatically when examples are run.
+
+== Common Patterns
+
+=== Basic Generation
+
+[source,ruby]
+----
+require "xseed"
+
+generator = Xseed::Svg::SvgGenerator.new("schema.xsd")
+svg_content = generator.generate
+----
+
+=== Generate to File
+
+[source,ruby]
+----
+require "xseed"
+
+generator = Xseed::Svg::SvgGenerator.new("schema.xsd")
+generator.generate_file("diagram.svg")
+----
+
+=== Inspect Schema First
+
+[source,ruby]
+----
+require "xseed"
+
+parser = Xseed::Parser::XsdParser.new("schema.xsd")
+puts "Elements: #{parser.elements.size}"
+puts "Types: #{parser.types.size}"
+
+# Then generate
+generator = Xseed::Svg::SvgGenerator.new("schema.xsd")
+generator.generate_file("diagram.svg")
+----
+
+=== Error Handling
+
+[source,ruby]
+----
+require "xseed"
+
+begin
+  generator = Xseed::Svg::SvgGenerator.new("schema.xsd")
+  generator.generate_file("output.svg")
+rescue Xseed::ParserError => e
+  puts "Parser error: #{e.message}"
+rescue Xseed::Svg::GenerationError => e
+  puts "Generation error: #{e.message}"
+end
+----
+
+=== Batch Processing
+
+[source,ruby]
+----
+require "xseed"
+
+Dir.glob("schemas/*.xsd").each do |xsd_file|
+  basename = File.basename(xsd_file, ".xsd")
+  output = "output/#{basename}-diagram.svg"
+
+  generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+  generator.generate_file(output)
+  puts "Generated: #{output}"
+end
+----
+
+== Integration Examples
+
+=== Rake Task
+
+[source,ruby]
+----
+# Rakefile
+require "xseed"
+
+desc "Generate SVG diagrams from XSD schemas"
+task :diagrams do
+  Dir.glob("schemas/*.xsd").each do |xsd|
+    svg = xsd.sub("schemas/", "docs/diagrams/").sub(".xsd", ".svg")
+    FileUtils.mkdir_p(File.dirname(svg))
+
+    generator = Xseed::Svg::SvgGenerator.new(xsd)
+    generator.generate_file(svg)
+    puts "Generated: #{svg}"
+  end
+end
+----
+
+=== Makefile
+
+[source,makefile]
+----
+# Makefile
+SCHEMAS = $(wildcard schemas/*.xsd)
+DIAGRAMS = $(SCHEMAS:schemas/%.xsd=docs/diagrams/%.svg)
+
+all: diagrams
+
+diagrams: $(DIAGRAMS)
+
+docs/diagrams/%.svg: schemas/%.xsd
+	@mkdir -p $(dir $@)
+	@xseed svg $< -o $@
+	@echo "Generated: $@"
+
+clean:
+	rm -rf docs/diagrams/*.svg
+
+.PHONY: all diagrams clean
+----
+
+=== CI/CD Pipeline
+
+[source,yaml]
+----
+# .github/workflows/diagrams.yml
+name: Generate Diagrams
+
+on:
+  push:
+    paths:
+      - 'schemas/**.xsd'
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+
+      - name: Generate SVG diagrams
+        run: |
+          bundle exec rake diagrams
+
+      - name: Commit diagrams
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+          git add docs/diagrams/*.svg
+          git commit -m "docs: regenerate SVG diagrams" || true
+          git push
+----
+
+== Customization Examples
+
+=== Custom Output Directory
+
+[source,ruby]
+----
+require "xseed"
+require "fileutils"
+
+output_dir = "custom/output/path"
+FileUtils.mkdir_p(output_dir)
+
+generator = Xseed::Svg::SvgGenerator.new("schema.xsd")
+output_file = File.join(output_dir, "diagram.svg")
+generator.generate_file(output_file)
+----
+
+=== Conditional Generation
+
+[source,ruby]
+----
+require "xseed"
+
+xsd_file = "schema.xsd"
+parser = Xseed::Parser::XsdParser.new(xsd_file)
+
+# Only generate if schema is complex enough
+if parser.types.size > 5
+  generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+  generator.generate_file("diagram.svg")
+  puts "Generated diagram for complex schema"
+else
+  puts "Schema too simple, skipping diagram"
+end
+----
+
+=== Performance Monitoring
+
+[source,ruby]
+----
+require "xseed"
+require "benchmark"
+
+xsd_file = "schema.xsd"
+
+elapsed = Benchmark.realtime do
+  generator = Xseed::Svg::SvgGenerator.new(xsd_file)
+  generator.generate_file("diagram.svg")
+end
+
+puts "Generation took: #{(elapsed * 1000).round(2)}ms"
+----
+
+== Troubleshooting
+
+=== Missing Dependencies
+
+If examples fail with "cannot load such file" errors:
+
+[source,shell]
+----
+# Install dependencies
+bundle install
+
+# Run examples from project root
+cd /path/to/xseed
+ruby examples/simple_generation.rb
+----
+
+=== Permission Errors
+
+If you get permission errors when writing files:
+
+[source,shell]
+----
+# Make output directory writable
+chmod 755 examples/output
+
+# Or run with appropriate permissions
+----
+
+=== Schema Not Found
+
+Ensure schema files exist in the expected locations:
+
+[source,shell]
+----
+# Check schema files
+ls examples/schemas/
+
+# Use absolute paths if needed
+ruby -e 'puts File.expand_path("examples/schemas/person.xsd")'
+----
+
+== Additional Resources
+
+* link:../README.adoc[Main README]
+* link:../docs/SVG_GENERATION.adoc[SVG Generation Guide]
+* link:../docs/ARCHITECTURE.adoc[Technical Architecture]
+* https://github.com/metanorma/xseed[GitHub Repository]
+
+== Contributing Examples
+
+To contribute new examples:
+
+1. Create a descriptive Ruby file in `examples/`
+2. Include clear comments explaining the example
+3. Add error handling
+4. Update this README
+5. Test the example works standalone
+
+Examples should:
+
+* Be self-contained
+* Include error handling
+* Use the person.xsd schema when possible
+* Output to `examples/output/`
+* Include helpful console output