sirena 0.1.0

data/docs/_guides/cli-reference.adoc

@@ -0,0 +1,203 @@
+---
+layout: default
+title: CLI Reference
+parent: Guides
+nav_order: 3
+---
+
+= CLI Reference
+
+Complete reference for all Sirena command-line interface commands.
+
+== Global Options
+
+These options are available for all commands:
+
+`--verbose, -v`::
+Enable verbose output for debugging
+
+`--help, -h`::
+Show help for the command
+
+== Commands
+
+=== render
+
+Render a single Mermaid diagram to SVG.
+
+[source,shell]
+----
+sirena render INPUT [OPTIONS]
+----
+
+==== Arguments
+
+`INPUT`:: Path to input Mermaid file (.mmd)
+
+==== Options
+
+`--output, -o PATH`:: Output SVG file path (default: stdout)
+
+`--type, -t TYPE`:: Explicitly specify diagram type (auto-detected if not provided)
+
+`--theme THEME`:: Theme to use: default, dark, light, high-contrast
+
+==== Examples
+
+Render to stdout:
+[source,shell]
+----
+sirena render diagram.mmd
+----
+
+Render to file:
+[source,shell]
+----
+sirena render diagram.mmd -o output.svg
+----
+
+Specify diagram type:
+[source,shell]
+----
+sirena render diagram.mmd -t flowchart -o output.svg
+----
+
+Use dark theme:
+[source,shell]
+----
+sirena render diagram.mmd --theme dark -o output.svg
+----
+
+=== batch
+
+Render multiple Mermaid diagrams in a directory.
+
+[source,shell]
+----
+sirena batch INPUT_DIR [OPTIONS]
+----
+
+==== Arguments
+
+`INPUT_DIR`:: Directory containing Mermaid files
+
+==== Options
+
+`--output, -o DIR`:: Output directory for SVG files (default: current directory)
+
+`--theme THEME`:: Theme to use for all diagrams
+
+`--recursive, -r`:: Process subdirectories recursively
+
+==== Examples
+
+Render all diagrams in a directory:
+[source,shell]
+----
+sirena batch diagrams/ -o output/
+----
+
+Process recursively:
+[source,shell]
+----
+sirena batch diagrams/ -o output/ --recursive
+----
+
+=== types
+
+List all supported diagram types.
+
+[source,shell]
+----
+sirena types
+----
+
+==== Output
+
+Displays all 24 supported diagram types with their identifiers.
+
+==== Example
+
+[source,shell]
+----
+sirena types
+----
+
+Output:
+----
+Supported diagram types:
+  - architecture
+  - block
+  - c4
+  - class
+  - er
+  - error
+  - flowchart
+  - gantt
+  - gitgraph
+  - info
+  - journey
+  - kanban
+  - mindmap
+  - packet
+  - pie
+  - quadrant
+  - radar
+  - requirement
+  - sankey
+  - sequence
+  - state
+  - timeline
+  - treemap
+  - xychart
+----
+
+=== version
+
+Display Sirena version.
+
+[source,shell]
+----
+sirena version
+----
+
+==== Example
+
+[source,shell]
+----
+sirena version
+----
+
+Output:
+----
+Sirena version 0.1.0
+----
+
+== Environment Variables
+
+`SIRENA_THEME`:: Default theme (overridden by --theme option)
+
+`SIRENA_VERBOSE`:: Enable verbose mode (set to 1 or true)
+
+==== Example
+
+[source,shell]
+----
+export SIRENA_THEME=dark
+export SIRENA_VERBOSE=1
+sirena render diagram.mmd -o output.svg
+----
+
+== Exit Codes
+
+`0`:: Success
+`1`:: General error
+`2`:: File not found
+`3`:: Parse error
+`4`:: Render error
+
+== Next Steps
+
+* link:../diagram_types/index.html[Diagram Types Reference] - Syntax for all 24 types
+* link:quick-start.html[Quick Start Guide] - Get started quickly
+* link:../../examples/README.html[Examples] - Browse working examples

data/docs/_guides/index.adoc

@@ -0,0 +1,56 @@
+---
+layout: default
+title: Guides
+nav_order: 4
+has_children: true
+---
+
+== Guides
+
+In-depth guides covering advanced topics, best practices, and real-world use cases.
+
+== What's in This Section
+
+Comprehensive guides for:
+
+* **Migration from Mermaid.js** - Converting from JavaScript to Ruby
+* **Performance Optimization** - Making your diagrams render faster
+* **Advanced Theming** - Deep dive into the theme system
+* **Best Practices** - Patterns and anti-patterns for each diagram type
+* **Troubleshooting** - Debugging common issues
+* **Production Deployment** - Running Sirena in production environments
+
+== Guide Format
+
+Each guide provides:
+
+* **Overview** - What the guide covers
+* **Background** - Context and concepts
+* **Detailed explanations** - In-depth technical information
+* **Examples** - Real-world scenarios
+* **Best practices** - Recommended approaches
+* **Common pitfalls** - What to avoid
+
+== Featured Guides
+
+=== For Mermaid.js Users
+
+* link:{% link _guides/migration-from-mermaid.adoc %}[Migration from Mermaid.js] - Complete migration guide with syntax comparison
+
+=== For Production Use
+
+* link:{% link _guides/performance-optimization.adoc %}[Performance Optimization] - Techniques for faster rendering
+* link:{% link _guides/caching-strategies.adoc %}[Caching Strategies] - Improve performance with caching
+* link:{% link _guides/ci-cd-integration.adoc %}[CI/CD Integration] - Using Sirena in automated workflows
+
+=== For Advanced Customization
+
+* link:{% link _guides/custom-themes.adoc %}[Creating Custom Themes] - Building themes from scratch
+* link:{% link _guides/svg-customization.adoc %}[SVG Customization] - Advanced SVG manipulation
+* link:{% link _guides/extending-parsers.adoc %}[Extending Parsers] - Adding custom syntax
+
+== Related Documentation
+
+* link:{% link _tutorials/index.adoc %}[Tutorials] - For step-by-step learning
+* link:{% link _features/index.adoc %}[Features] - For feature documentation
+* link:{% link _references/index.adoc %}[References] - For API and CLI reference

data/docs/_guides/installation.adoc

@@ -0,0 +1,100 @@
+---
+layout: default
+title: Installation
+parent: Guides
+nav_order: 1
+---
+
+= Installation Guide
+
+== Requirements
+
+Sirena requires:
+
+* Ruby 2.7 or higher
+* Bundler (for development)
+
+== Installation Methods
+
+=== Via RubyGems (Recommended)
+
+Install Sirena directly from RubyGems:
+
+[source,shell]
+----
+gem install sirena
+----
+
+=== Via Bundler
+
+Add Sirena to your `Gemfile`:
+
+[source,ruby]
+----
+gem 'sirena'
+----
+
+Then install:
+
+[source,shell]
+----
+bundle install
+----
+
+=== From Source
+
+Clone the repository and install locally:
+
+[source,shell]
+----
+git clone https://github.com/claricle/sirena.git
+cd sirena
+bundle install
+bundle exec rake install
+----
+
+== Verification
+
+Verify the installation:
+
+[source,shell]
+----
+sirena version
+----
+
+You should see output similar to:
+
+----
+Sirena version 0.1.0
+----
+
+== Next Steps
+
+* link:quick-start.html[Quick Start Guide] - Get started with your first diagram
+* link:cli-reference.html[CLI Reference] - Learn all available commands
+* link:../diagram_types/index.html[Diagram Types] - Explore all 24 diagram types
+
+== Troubleshooting
+
+=== Command Not Found
+
+If `sirena` command is not found after installation, ensure your gem bin directory is in your PATH:
+
+[source,shell]
+----
+echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+----
+
+Replace `X.X.0` with your Ruby version.
+
+=== Permission Errors
+
+If you encounter permission errors during installation, try:
+
+[source,shell]
+----
+gem install sirena --user-install
+----
+
+Or use a Ruby version manager like `rbenv` or `rvm`.

data/docs/_guides/quick-start.adoc

@@ -0,0 +1,132 @@
+---
+layout: default
+title: Quick Start
+parent: Guides
+nav_order: 2
+---
+
+= Quick Start Guide
+
+This guide will help you create your first diagram with Sirena in 5 minutes.
+
+== Prerequisites
+
+Ensure Sirena is installed. If not, see the link:installation.html[Installation Guide].
+
+== Your First Diagram
+
+=== Step 1: Create a Mermaid File
+
+Create a file named `my-first-diagram.mmd`:
+
+[source,mermaid]
+----
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Process]
+    B -->|No| D[End]
+    C --> D
+----
+
+=== Step 2: Render to SVG
+
+Run Sirena to generate an SVG:
+
+[source,shell]
+----
+sirena render my-first-diagram.mmd -o output.svg
+----
+
+=== Step 3: View the Result
+
+Open `output.svg` in your browser or image viewer to see your flowchart!
+
+== Common Diagram Types
+
+=== Flowchart
+
+[source,mermaid]
+----
+graph LR
+    A[Input] --> B[Process]
+    B --> C[Output]
+----
+
+=== Sequence Diagram
+
+[source,mermaid]
+----
+sequenceDiagram
+    Alice->>Bob: Hello
+    Bob-->>Alice: Hi there!
+----
+
+=== Entity-Relationship Diagram
+
+[source,mermaid]
+----
+erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+----
+
+== Programmatic Usage
+
+Use Sirena in your Ruby code:
+
+[source,ruby]
+----
+require 'sirena'
+
+# Render from a string
+mermaid_code = <<~MERMAID
+  graph TD
+    A --> B
+MERMAID
+
+svg = Sirena::Engine.render(mermaid_code)
+File.write('output.svg', svg)
+
+# Render from a file
+svg = Sirena::Engine.render_file('diagram.mmd')
+----
+
+== Batch Processing
+
+Render multiple diagrams at once:
+
+[source,shell]
+----
+sirena batch diagrams/ -o output/
+----
+
+This renders all `.mmd` files in `diagrams/` directory to SVG files in `output/`.
+
+== Next Steps
+
+* link:cli-reference.html[CLI Reference] - Learn all available commands and options
+* link:../diagram_types/index.html[Diagram Types Reference] - Explore all 24 diagram types
+* link:../../examples/README.html[Examples] - Browse 37+ working examples
+
+== Getting Help
+
+View available commands:
+
+[source,shell]
+----
+sirena help
+----
+
+View help for a specific command:
+
+[source,shell]
+----
+sirena help render
+----
+
+List all supported diagram types:
+
+[source,shell]
+----
+sirena types
+----