serialbench 0.1.0 → 0.1.1

data/README.adoc

@@ -1,31 +1,282 @@
-= Serialbench: Comprehensive serialization benchmarking suite for Ruby
+= Serialbench: Ruby serialization library performance benchmarker
 
 image:https://img.shields.io/gem/v/serialbench.svg["Gem Version", link="https://rubygems.org/gems/serialbench"]
-image:https://github.com/example/serialbench/actions/workflows/rake.yml/badge.svg["Build Status", link="https://github.com/example/serialbench/actions/workflows/rake.yml"]
-image:https://img.shields.io/github/issues-pr-raw/example/serialbench.svg["Pull Requests", link="https://github.com/example/serialbench/pulls"]
-image:https://img.shields.io/github/commits-since/example/serialbench/latest.svg["Commits since latest",link="https://github.com/example/serialbench/releases"]
+image:https://github.com/metanorma/serialbench/actions/workflows/ci.yml/badge.svg["Build Status", link="https://github.com/metanorma/serialbench/actions/workflows/ci.yml"]
+image:https://github.com/metanorma/serialbench/actions/workflows/benchmark.yml/badge.svg["Benchmark Status", link="https://github.com/metanorma/serialbench/actions/workflows/benchmark.yml"]
+image:https://img.shields.io/github/issues-pr-raw/metanorma/serialbench.svg["Pull Requests", link="https://github.com/metanorma/serialbench/pulls"]
 
-== Purpose
+== Overview
 
-Serialbench is a comprehensive benchmarking suite that evaluates the performance of popular Ruby serialization libraries across multiple formats and dimensions including parsing speed, generation speed, memory usage, and feature completeness.
+Serialbench is a comprehensive benchmarking suite that evaluates the performance of popular Ruby serialization libraries across multiple formats. It provides detailed performance comparisons and analysis to help developers make informed decisions when choosing serialization libraries for their Ruby applications.
 
-This tool helps developers make informed decisions when choosing serialization libraries for their Ruby applications by providing detailed performance comparisons and analysis across XML, JSON, and TOML formats.
+**Supported Formats**: XML, JSON, YAML, TOML, and more
 
-=== Tested XML libraries
+**Key Metrics**: Parsing speed, generation speed, memory usage, streaming capabilities, and feature completeness
 
-==== Core XML Libraries
-* **Ox** - High-performance XML parser optimized for speed and low memory usage
-* **Nokogiri** - Feature-rich XML/HTML parser with XPath support and comprehensive DOM manipulation
-* **LibXML** - Ruby bindings for the libxml2 C library with excellent performance characteristics
-* **Oga** - Pure Ruby XML parser with XPath support and streaming capabilities
-* **REXML** - Ruby's built-in XML parser with streaming support (reference implementation)
+**Docker Support**: Multi-Ruby version benchmarking with automated result aggregation and GitHub Pages generation
 
-==== Additional Format Support
-* **JSON** - Ruby's built-in JSON parser (for comparison baseline)
-* **Oj** - High-performance JSON parser with streaming support (for comparison baseline)
-* **YAJL** - Yet Another JSON Library with streaming support (for comparison baseline)
-* **TOML-RB** - Ruby TOML parser (for comparison baseline)
-* **Tomlib** - Fast TOML parser (for comparison baseline)
+== Supported serialization libraries
+
+[cols="1,3,1,4", options="header"]
+|===
+| Format | Name | Version | Description
+
+| XML
+| https://github.com/ohler55/ox[Ox]
+| v2.14.23
+| C extension XML parser
+
+| XML
+| https://github.com/xml4r/libxml-ruby[LibXML]
+| v4.1.2
+| Ruby bindings for libxml2
+
+| XML
+| https://github.com/sparklemotion/nokogiri[Nokogiri]
+| v1.18.8
+| XML/HTML parser with XPath and CSS selectors
+
+| XML
+| https://github.com/YorickPeterse/oga[Oga]
+| v3.4
+| Pure Ruby XML parser with XPath support
+
+| XML
+| https://github.com/ruby/rexml[REXML]
+| v3.4.1
+| Ruby's standard library XML parser
+
+| JSON
+| https://github.com/ohler55/oj[Oj]
+| v3.16.11
+| JSON parser with multiple parsing modes
+
+| JSON
+| https://github.com/brianmario/yajl-ruby[YAJL]
+| v1.4.3
+| JSON library with streaming capabilities
+
+| JSON
+| https://github.com/flori/json[JSON]
+| v2.12.2
+| Ruby's standard library JSON parser
+
+| YAML
+| https://github.com/ruby/psych[Psych]
+| v5.1.2
+| Ruby's standard library YAML parser
+
+| YAML
+| https://github.com/ruby/syck[Syck]
+| v1.5.1.1
+| Legacy YAML parser
+
+| TOML
+| https://github.com/fbernier/tomlib[Tomlib]
+| v0.7.3
+| TOML parser implemented in C
+
+| TOML
+| https://github.com/emancu/toml-rb[TOML-RB]
+| v2.2.0
+| Pure Ruby TOML parser
+|===
+
+== Benchmark report JSON format
+
+=== Single Ruby version results
+
+The benchmark results are saved as JSON files with the following structure:
+
+[source,json]
+----
+{
+  "environment": {
+    "ruby_version": "3.3.8",
+    "ruby_platform": "aarch64-linux",
+    "serializer_versions": {
+      "rexml": "3.4.1",
+      "ox": "2.14.23",
+      "nokogiri": "1.18.8",
+      "oga": "3.4",
+      "libxml": "4.1.2",
+      "json": "2.12.2",
+      "oj": "3.16.11",
+      "yajl": "1.4.3",
+      "psych": "5.1.2",
+      "syck": "1.5.1.1",
+      "toml-rb": "2.2.0",
+      "tomlib": "0.7.3"
+    },
+    "timestamp": "2025-06-07T09:00:25+00:00"
+  },
+  "parsing": {
+    "small": {
+      "xml": {
+        "rexml": {
+          "time_per_iterations": 0.002514416000053643,
+          "time_per_iteration": 0.00012572080000268216,
+          "iterations_per_second": 7954.133285650949,
+          "iterations_count": 20
+        },
+        "ox": {
+          "time_per_iterations": 0.00005258399994545471,
+          "time_per_iteration": 0.0000026291999972727353,
+          "iterations_per_second": 380343.83121759404,
+          "iterations_count": 20
+        }
+      },
+      "json": {
+        "json": {
+          "time_per_iterations": 0.000029707999942729657,
+          "time_per_iteration": 0.000001485399997136483,
+          "iterations_per_second": 673219.3361571126,
+          "iterations_count": 20
+        },
+        "oj": {
+          "time_per_iterations": 0.00003158300000905001,
+          "time_per_iteration": 0.0000015791500004525006,
+          "iterations_per_second": 633252.0658034089,
+          "iterations_count": 20
+        }
+      }
+    },
+    "medium": {
+      "xml": { /* ... */ },
+      "json": { /* ... */ }
+    },
+    "large": {
+      "xml": { /* ... */ },
+      "json": { /* ... */ }
+    }
+  },
+  "ruby_version": "3.3.8",
+  "ruby_platform": "aarch64-linux",
+  "timestamp": "2025-06-07T09:01:02+00:00"
+}
+----
+
+=== Multi-Ruby version merged results
+
+When results from multiple Ruby versions are merged, the structure becomes:
+
+[source,json]
+----
+{
+  "environments": {
+    "3_3_8_aarch64_linux": {
+      "ruby_version": "3.3.8",
+      "ruby_platform": "aarch64-linux",
+      "source_file": "docker-results/ruby-3.3/data/results.json",
+      "timestamp": "2025-06-07T09:01:02+00:00",
+      "environment": {
+        "ruby_version": "3.3.8",
+        "ruby_platform": "aarch64-linux",
+        "serializer_versions": { /* ... */ },
+        "timestamp": "2025-06-07T09:00:25+00:00"
+      }
+    },
+    "3_4_4_aarch64_linux": {
+      "ruby_version": "3.4.4",
+      "ruby_platform": "aarch64-linux",
+      /* ... */
+    }
+  },
+  "combined_results": {
+    "parsing": {
+      "small": {
+        "xml": {
+          "rexml": {
+            "3_3_8_aarch64_linux": {
+              "time_per_iterations": 0.002514416000053643,
+              "time_per_iteration": 0.00012572080000268216,
+              "iterations_per_second": 7954.133285650949,
+              "iterations_count": 20
+            },
+            "3_4_4_aarch64_linux": {
+              "time_per_iterations": 0.0025308329999234047,
+              "time_per_iteration": 0.00012654164999617023,
+              "iterations_per_second": 7902.536437846866,
+              "iterations_count": 20
+            }
+          }
+        }
+      }
+    }
+  },
+  "metadata": {
+    "merged_at": "2025-06-07T17:01:48+08:00",
+    "ruby_versions": ["3.3.8", "3.4.4"],
+    "platforms": ["aarch64-linux"]
+  }
+}
+----
+
+=== JSON schema specification
+
+The benchmark results follow this schema:
+
+[source,json]
+----
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Serialbench Results",
+  "type": "object",
+  "properties": {
+    "environment": {
+      "type": "object",
+      "properties": {
+        "ruby_version": { "type": "string" },
+        "ruby_platform": { "type": "string" },
+        "serializer_versions": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "timestamp": { "type": "string", "format": "date-time" }
+      },
+      "required": ["ruby_version", "ruby_platform", "serializer_versions", "timestamp"]
+    },
+    "parsing": {
+      "type": "object",
+      "properties": {
+        "small": { "$ref": "#/definitions/sizeResults" },
+        "medium": { "$ref": "#/definitions/sizeResults" },
+        "large": { "$ref": "#/definitions/sizeResults" }
+      }
+    },
+    "ruby_version": { "type": "string" },
+    "ruby_platform": { "type": "string" },
+    "timestamp": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "sizeResults": {
+      "type": "object",
+      "properties": {
+        "xml": { "$ref": "#/definitions/formatResults" },
+        "json": { "$ref": "#/definitions/formatResults" },
+        "yaml": { "$ref": "#/definitions/formatResults" },
+        "toml": { "$ref": "#/definitions/formatResults" }
+      }
+    },
+    "formatResults": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/serializerResults"
+      }
+    },
+    "serializerResults": {
+      "type": "object",
+      "properties": {
+        "time_per_iterations": { "type": "number" },
+        "time_per_iteration": { "type": "number" },
+        "iterations_per_second": { "type": "number" },
+        "iterations_count": { "type": "integer" }
+      },
+      "required": ["time_per_iterations", "time_per_iteration", "iterations_per_second", "iterations_count"]
+    }
+  }
+}
+----
 
 == Installation
 
@@ -38,14 +289,14 @@ gem 'serialbench'
 
 And then execute:
 
-[source,shell]
+[source]
 ----
 $ bundle install
 ----
 
 Or install it yourself as:
 
-[source,shell]
+[source]
 ----
 $ gem install serialbench
 ----
@@ -54,7 +305,8 @@ $ gem install serialbench
 
 To run benchmarks for all supported XML libraries, install the following gems:
 
-[source,shell]
+
+[source]
 ----
 # Core XML libraries
 $ gem install ox nokogiri libxml-ruby oga
@@ -66,20 +318,25 @@ $ gem install oj toml-rb
 $ gem install memory_profiler
 ----
 
-NOTE: REXML and JSON are included with Ruby and require no additional installation.
+
+NOTE: REXML, JSON, and Psych (YAML) are included with Ruby and require no additional installation.
 
 === Library-specific installation notes
 
 ==== Ox
+
 High-performance C extension requiring compilation:
-[source,shell]
+
+[source]
 ----
 $ gem install ox
 ----
 
 ==== Nokogiri
+
 May require system dependencies on some platforms:
-[source,shell]
+
+[source]
 ----
 # macOS with Homebrew
 $ brew install libxml2 libxslt
@@ -91,8 +348,10 @@ $ gem install nokogiri
 ----
 
 ==== LibXML
+
 Ruby bindings for libxml2:
-[source,shell]
+
+[source]
 ----
 # macOS with Homebrew
 $ brew install libxml2
@@ -104,77 +363,531 @@ $ gem install libxml-ruby
 ----
 
 ==== Oga
+
 Pure Ruby implementation with no system dependencies:
-[source,shell]
+
+[source]
 ----
 $ gem install oga
 ----
 
-== Usage
+== Docker containers and cross-platform benchmarking
 
-=== Command line interface
+Serialbench provides pre-built Docker containers and supports cross-platform benchmarking on Windows, macOS, and Linux. Our containers are automatically built and published to GitHub Container Registry for easy access.
+
+=== Published Docker containers
+
+We publish multi-architecture Docker containers for all supported Ruby versions:
+
+**Registry**: `ghcr.io/metanorma/serialbench`
+
+**Available tags**:
+* `ghcr.io/metanorma/serialbench:main-ruby-3.1` - Ruby 3.1 (linux/amd64, linux/arm64)
+* `ghcr.io/metanorma/serialbench:main-ruby-3.2` - Ruby 3.2 (linux/amd64, linux/arm64)
+* `ghcr.io/metanorma/serialbench:main-ruby-3.3` - Ruby 3.3 (linux/amd64, linux/arm64)
+* `ghcr.io/metanorma/serialbench:main-ruby-3.4` - Ruby 3.4 (linux/amd64, linux/arm64)
+
+**Container features**:
+* All serialization libraries pre-installed (XML, JSON, YAML, TOML)
+* Multi-architecture support (Intel x64 and ARM64)
+* Optimized for CI/CD and local development
+* Automatic updates on code changes
+
+=== Running benchmarks on your computer
 
-Run the complete XML benchmark suite:
+==== Windows (PowerShell/Command Prompt)
 
-[source,shell]
+[source,powershell]
 ----
-$ serialbench benchmark
+# Pull and run latest Ruby 3.3 container
+docker pull ghcr.io/metanorma/serialbench:main-ruby-3.3
+
+# Create results directory
+mkdir results
+
+# Run benchmarks with volume mounting
+docker run --rm -v ${PWD}/results:/app/results ghcr.io/metanorma/serialbench:main-ruby-3.3
+
+# View results
+dir results
 ----
 
-Run XML-only benchmarks:
+==== macOS (Terminal)
 
-[source,shell]
+[source,bash]
 ----
-$ serialbench benchmark --formats xml
+# Pull and run latest Ruby 3.3 container
+docker pull ghcr.io/metanorma/serialbench:main-ruby-3.3
+
+# Create results directory
+mkdir -p results
+
+# Run benchmarks with volume mounting
+docker run --rm -v $(pwd)/results:/app/results ghcr.io/metanorma/serialbench:main-ruby-3.3
+
+# View results
+ls -la results/
 ----
 
-Run benchmarks with comparison formats:
+==== Ubuntu/Linux (Terminal)
 
-[source,shell]
+[source,bash]
 ----
-$ serialbench benchmark --formats xml json
-$ serialbench benchmark --formats xml json toml
+# Pull and run latest Ruby 3.3 container
+docker pull ghcr.io/metanorma/serialbench:main-ruby-3.3
+
+# Create results directory
+mkdir -p results
+
+# Run benchmarks with volume mounting
+docker run --rm -v $(pwd)/results:/app/results ghcr.io/metanorma/serialbench:main-ruby-3.3
+
+# View results
+ls -la results/
 ----
 
-Run only DOM parsing benchmarks:
+=== Multi-Ruby version comparison
+
+Run benchmarks across all supported Ruby versions:
+
+==== Windows (PowerShell)
 
-[source,shell]
+[source,powershell]
 ----
-$ serialbench benchmark --parsing-only
+# Create results directories
+$versions = @("3.1", "3.2", "3.3", "3.4")
+foreach ($version in $versions) {
+    mkdir "results-ruby-$version" -Force
+    docker pull "ghcr.io/metanorma/serialbench:main-ruby-$version"
+    docker run --rm -v "${PWD}/results-ruby-${version}:/app/results" "ghcr.io/metanorma/serialbench:main-ruby-$version"
+}
+
+# View all results
+dir results-ruby-*
 ----
 
-Run only XML generation benchmarks:
+==== macOS/Linux (Bash)
 
-[source,shell]
+[source,bash]
 ----
-$ serialbench benchmark --generation-only
+# Run benchmarks for all Ruby versions
+for version in 3.1 3.2 3.3 3.4; do
+    echo "Running benchmarks for Ruby $version..."
+    mkdir -p "results-ruby-$version"
+    docker pull "ghcr.io/metanorma/serialbench:main-ruby-$version"
+    docker run --rm \
+        -v "$(pwd)/results-ruby-$version:/app/results" \
+        "ghcr.io/metanorma/serialbench:main-ruby-$version"
+done
+
+# View all results
+ls -la results-ruby-*/
 ----
 
-Run only streaming/SAX parsing benchmarks:
+=== Custom benchmark configuration
+
+Run benchmarks with custom parameters:
 
-[source,shell]
+[source,bash]
 ----
-$ serialbench benchmark --streaming-only
+# Run specific formats only
+docker run --rm \
+    -v $(pwd)/results:/app/results \
+    ghcr.io/metanorma/serialbench:main-ruby-3.3 \
+    bundle exec serialbench benchmark --formats xml json --iterations 10
+
+# Run with memory profiling
+docker run --rm \
+    -v $(pwd)/results:/app/results \
+    ghcr.io/metanorma/serialbench:main-ruby-3.3 \
+    bundle exec serialbench benchmark --memory-profiling
+
+# List available serializers
+docker run --rm ghcr.io/metanorma/serialbench:main-ruby-3.3 \
+    bundle exec serialbench list
 ----
 
-Output results in JSON format only:
+=== Quick start with Docker
 
-[source,shell]
+==== Prerequisites
+
+* Docker installed and running
+* Command line access (PowerShell, Terminal, or Bash)
+
+==== Running multi-Ruby benchmarks
+
+[source]
 ----
-$ serialbench benchmark --output-format json
+# From the project root directory (if you have the source)
+$ ./docker/run-benchmarks.sh
+
+# Or using published containers directly
+$ docker pull ghcr.io/metanorma/serialbench:main-ruby-3.3
+$ docker run --rm -v $(pwd)/results:/app/results ghcr.io/metanorma/serialbench:main-ruby-3.3
+----
+
+This will:
+
+. **Pull pre-built containers** from GitHub Container Registry
+. **Run comprehensive benchmarks** in isolated environments
+. **Generate detailed reports** with performance comparisons
+. **Output results** to your local `results/` directory
+
+==== Results structure
+
+Results are organized in `docker-results/`:
+
+[source]
+----
+docker-results/
+├── ruby-3.0/              # Ruby 3.0 individual results
+│   ├── benchmark.log       # Execution log
+│   ├── data/
+│   │   ├── results.json    # Raw benchmark data
+│   │   └── results.yaml    # YAML format results
+│   ├── reports/
+│   │   └── benchmark_report.html
+│   └── assets/
+├── ruby-3.1/              # Ruby 3.1 individual results
+├── ruby-3.2/              # Ruby 3.2 individual results
+├── ruby-3.3/              # Ruby 3.3 individual results
+├── ruby-3.4/              # Ruby 3.4 individual results
+├── merged/                 # Aggregated cross-version results
+│   └── merged_results.json # Combined performance data
+└── docs/                   # GitHub Pages ready output
+    ├── index.html          # Interactive comparison report
+    ├── styles.css          # Report styling
+    └── merged_results.json # Data for interactive charts
+----
+
+=== Manual Docker usage
+
+==== Build image for specific Ruby version
+
+[source]
+----
+$ docker build \
+  --build-arg RUBY_VERSION=3.3 \
+  -t serialbench:ruby-3.3 \
+  -f docker/Dockerfile.benchmark \
+  .
+----
+
+==== Run benchmarks in container
+
+[source]
+----
+# Create results directory
+$ mkdir -p results
+
+# Run benchmarks with volume mounting
+$ docker run \
+  --rm \
+  -v $(pwd)/results:/app/results \
+  serialbench:ruby-3.3
+----
+
+==== Custom configuration
+
+[source]
+----
+# Use custom config file
+$ docker run \
+  --rm \
+  -v $(pwd)/results:/app/results \
+  -v $(pwd)/config:/app/config \
+  serialbench:ruby-3.3 \
+  bundle exec serialbench benchmark --config config/ci.yml
+----
+
+=== Supported Ruby versions
+
+The Docker setup supports the following Ruby versions:
+
+* **Ruby 3.0** - Stable release with good performance baseline
+* **Ruby 3.1** - Improved performance and new features
+* **Ruby 3.2** - Enhanced YJIT and memory optimizations
+* **Ruby 3.3** - Latest stable with performance improvements
+* **Ruby 3.4** - Current development version
+
+Each version includes all supported serialization libraries:
+
+* **XML**: REXML (built-in), Ox, Nokogiri, Oga, LibXML
+* **JSON**: JSON (built-in), Oj, YAJL
+* **YAML**: Psych (built-in), Syck
+* **TOML**: TOML-RB, Tomlib
+
+=== Environment variables
+
+The Docker images support these environment variables:
+
+* `BUNDLE_PATH` - Bundle installation path
+* `BUNDLE_BIN` - Bundle binary path
+* `PATH` - System PATH including bundle binaries
+* `RUBY_VERSION` - Ruby version for build-time configuration
+
+=== Result aggregation and GitHub Pages
+
+==== Merging multi-version results
+
+The Docker workflow automatically merges results from all Ruby versions:
+
+[source]
+----
+# Manual result merging
+$ serialbench merge_results \
+  docker-results/ruby-3.0 \
+  docker-results/ruby-3.1 \
+  docker-results/ruby-3.2 \
+  docker-results/ruby-3.3 \
+  docker-results/ruby-3.4 \
+  docker-results/merged
+----
+
+==== GitHub Pages generation
+
+Generate interactive HTML reports ready for GitHub Pages deployment:
+
+[source]
+----
+# Generate GitHub Pages from multi-version results
+$ serialbench github_pages \
+  docker-results/ruby-3.0 \
+  docker-results/ruby-3.1 \
+  docker-results/ruby-3.2 \
+  docker-results/ruby-3.3 \
+  docker-results/ruby-3.4 \
+  docker-results/docs
 ----
 
-List available XML parsers:
+The generated GitHub Pages include:
 
-[source,shell]
+* **Interactive Performance Charts**: Compare serializers across Ruby versions
+* **Multi-Version Analysis**: See how performance changes between Ruby releases
+* **Environment Details**: Ruby versions, platforms, and library versions
+* **Responsive Design**: Works on desktop and mobile devices
+* **Direct Deployment**: Ready for GitHub Pages, Netlify, or any static hosting
+
+==== Deploying to GitHub Pages
+
+. **Commit the generated files**:
++
+[source]
+----
+$ git add docker-results/docs/
+$ git commit -m "Add multi-Ruby benchmark results"
+$ git push origin main
+----
+
+. **Enable GitHub Pages** in repository settings:
+.. Go to Settings → Pages
+.. Set source to "Deploy from a branch"
+.. Select branch containing the `docs/` folder
+.. Set folder to `/docker-results/docs`
+
+. **Access your results** at: `https://yourusername.github.io/yourrepo/`
+
+=== Troubleshooting Docker issues
+
+==== Build failures
+
+Check build logs for specific Ruby versions:
+
+[source]
+----
+$ cat docker-results/build-ruby-3.3.log
+----
+
+Common build issues:
+
+* **Missing system dependencies**: Ensure libxml2-dev and libxslt1-dev are available
+* **Network timeouts**: Retry the build or use a different network
+* **Disk space**: Ensure sufficient disk space for multiple Ruby images
+
+==== Runtime failures
+
+Check benchmark execution logs:
+
+[source]
+----
+$ cat docker-results/ruby-3.3/benchmark.log
+----
+
+Common runtime issues:
+
+* **Memory constraints**: Increase Docker memory allocation
+* **Timeout issues**: Some benchmarks may take longer on slower systems
+* **Permission errors**: Ensure proper volume mounting permissions
+
+==== Docker system issues
+
+Verify Docker is running properly:
+
+[source]
+----
+$ docker info
+$ docker system df  # Check disk usage
+$ docker system prune  # Clean up unused resources
+----
+
+Clean up Serialbench Docker resources:
+
+[source]
+----
+# Remove all Serialbench images
+$ docker rmi $(docker images serialbench -q)
+
+# Remove all containers
+$ docker container prune
+----
+
+=== Customization options
+
+==== Adding Ruby versions
+
+Edit the `RUBY_VERSIONS` array in `docker/run-benchmarks.sh`:
+
+[source,bash]
+----
+RUBY_VERSIONS=("3.0" "3.1" "3.2" "3.3" "3.4" "head")
+----
+
+==== Custom benchmark configuration
+
+Create custom config files in the `config/` directory:
+
+[source,yaml]
+----
+# config/custom.yml
+formats:
+  - xml
+  - json
+iterations: 50
+warmup: 5
+data_sizes:
+  - small
+  - medium
+----
+
+Reference the custom config in the run script:
+
+[source,bash]
+----
+# In docker/run-benchmarks.sh
+CONFIG_FILE="config/custom.yml"
+----
+
+==== Output directory customization
+
+Change the output directory in the run script:
+
+[source,bash]
+----
+# In docker/run-benchmarks.sh
+OUTPUT_DIR="my-benchmark-results"
+----
+
+=== Integration with CI/CD
+
+==== GitHub Actions integration
+
+The Docker setup integrates seamlessly with GitHub Actions:
+
+[source,yaml]
+----
+# .github/workflows/benchmark.yml
+name: Multi-Ruby Benchmarks
+
+on:
+  schedule:
+    - cron: '0 2 * * 0'  # Weekly on Sunday at 2 AM
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run Docker Benchmarks
+        run: ./docker/run-benchmarks.sh
+
+      - name: Upload Results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: docker-results/
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docker-results/docs
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: benchmark
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+----
+
+==== Performance considerations
+
+* **Parallel builds**: Docker builds can run in parallel for faster execution
+* **Build caching**: Subsequent runs use cached layers for faster builds
+* **Memory profiling**: Enabled by default but can be disabled for faster runs
+* **Result compression**: Large result files can be compressed for storage
+
+=== Security considerations
+
+* **Containers run with minimal privileges**: No root access required
+* **No network access during benchmarks**: Isolated execution environment
+* **Volume mounting**: Results written only to specified mounted volumes
+* **Image scanning**: Regular security updates for base Ruby images
+
+== Usage
+
+=== Command line interface
+
+==== Basic usage
+
+Run benchmarks for all available formats:
+
+[source]
+----
+$ serialbench benchmark
+----
+
+List all available serializers:
+
+[source]
 ----
 $ serialbench list
-$ serialbench list --format xml
 ----
 
 Show help information:
 
-[source,shell]
+[source]
 ----
 $ serialbench help
 $ serialbench help benchmark
@@ -182,47 +895,142 @@ $ serialbench help benchmark
 
 Show version:
 
-[source,shell]
+[source]
 ----
 $ serialbench version
 ----
 
-=== XML-specific benchmark options
+==== Format-specific benchmarks
+
+===== XML benchmarks
 
-Run benchmarks for specific XML libraries only:
+Run all XML library benchmarks:
 
-[source,shell]
+[source]
+----
+$ serialbench benchmark --formats xml
+----
+
+Test specific XML libraries:
+
+[source]
 ----
 $ serialbench benchmark --formats xml --parsers ox,nokogiri
-$ serialbench benchmark --formats xml --parsers rexml,oga
+$ serialbench benchmark --formats xml --parsers rexml,oga,libxml
+----
+
+XML-only parsing performance:
+
+[source]
+----
+$ serialbench benchmark --formats xml --parsing-only
+----
+
+XML generation benchmarks:
+
+[source]
+----
+$ serialbench benchmark --formats xml --generation-only
+----
+
+XML streaming/SAX parsing:
+
+[source]
+----
+$ serialbench benchmark --formats xml --streaming-only
 ----
 
-Run memory-intensive benchmarks:
+===== JSON benchmarks
+
+Run all JSON library benchmarks:
 
-[source,shell]
+[source]
 ----
-$ serialbench benchmark --formats xml --memory-profiling
+$ serialbench benchmark --formats json
 ----
 
-Generate detailed XML processing reports:
+Test specific JSON libraries:
 
-[source,shell]
+[source]
 ----
-$ serialbench benchmark --formats xml --detailed-reports
+$ serialbench benchmark --formats json --parsers oj,json
+$ serialbench benchmark --formats json --parsers yajl,oj
 ----
 
-=== Multi-Ruby Version Comparison
+===== TOML benchmarks
+
+Run all TOML library benchmarks:
+
+[source]
+----
+$ serialbench benchmark --formats toml
+----
+
+Test specific TOML libraries:
+
+[source]
+----
+$ serialbench benchmark --formats toml --parsers tomlib,toml-rb
+----
+
+==== Cross-format comparisons
+
+Compare XML vs JSON performance:
+
+[source]
+----
+$ serialbench benchmark --formats xml json
+----
+
+Compare all supported formats:
+
+[source]
+----
+$ serialbench benchmark --formats xml json toml
+----
+
+==== Advanced options
+
+Memory profiling across formats:
+
+[source]
+----
+$ serialbench benchmark --memory-profiling
+----
+
+Generate detailed reports:
+
+[source]
+----
+$ serialbench benchmark --detailed-reports
+----
+
+Output results in JSON format:
+
+[source]
+----
+$ serialbench benchmark --output-format json
+----
+
+Custom data sizes and iterations:
+
+[source]
+----
+$ serialbench benchmark --data-sizes small,medium --iterations 100
+----
+
+=== Multi-Ruby version comparison
 
 Merge benchmark results from multiple Ruby versions:
 
-[source,shell]
+[source]
 ----
 $ serialbench merge_results ruby-3.0/results ruby-3.1/results ruby-3.2/results merged_output/
 ----
 
 Generate GitHub Pages HTML from multiple benchmark runs:
 
-[source,shell]
+[source]
 ----
 $ serialbench github_pages ruby-3.0/results ruby-3.1/results ruby-3.2/results docs/
 ----
@@ -234,6 +1042,70 @@ This creates an interactive HTML report with:
 * **Environment details**: Ruby versions, platforms, and serializer versions
 * **GitHub Pages ready**: Deploy directly to GitHub Pages for public sharing
 
+=== Cross-platform performance analysis
+
+Analyze performance data from multiple benchmark runs across different platforms and Ruby versions:
+
+[source]
+----
+$ serialbench analyze_performance artifacts/benchmark-results-*/ performance_analysis.json
+----
+
+This command:
+
+* **Processes multiple result directories** from different platforms and Ruby versions
+* **Extracts platform and Ruby version** information from directory names
+* **Generates comprehensive JSON** with detailed performance metrics
+* **Handles both parsing and generation** benchmark results
+* **Provides summary statistics** about processed data
+
+Generate platform comparison reports:
+
+[source]
+----
+$ serialbench platform_comparison performance_analysis.json platform_comparison.json
+----
+
+This creates a JSON report with:
+
+* **Cross-platform statistics**: Average, min, max performance by platform
+* **Format-specific analysis**: Performance breakdown by serialization format
+* **Operation comparison**: Separate analysis for parsing vs generation
+* **Sample counts**: Number of data points for statistical confidence
+* **Standard deviation**: Statistical variance for performance consistency
+
+==== Example workflow for cross-platform analysis
+
+[source]
+----
+# 1. Run benchmarks on different platforms (or use CI artifacts)
+$ serialbench benchmark --formats xml json yaml toml
+
+# 2. Collect results from multiple platforms/Ruby versions
+$ mkdir analysis
+$ cp -r platform1-ruby3.2/results analysis/benchmark-results-ubuntu-ruby-3.2
+$ cp -r platform2-ruby3.3/results analysis/benchmark-results-macos-ruby-3.3
+$ cp -r platform3-ruby3.4/results analysis/benchmark-results-windows-ruby-3.4
+
+# 3. Generate performance analysis
+$ serialbench analyze_performance analysis/benchmark-results-*/ performance_analysis.json
+
+# 4. Create platform comparison report
+$ serialbench platform_comparison performance_analysis.json platform_comparison.json
+
+# 5. View results
+$ cat performance_analysis.json | jq '.summary'
+$ cat performance_analysis.json | jq '.platforms'
+$ cat platform_comparison.json | jq '.platforms'
+----
+
+The analysis commands are particularly useful for:
+
+* **CI/CD integration**: Automated cross-platform performance tracking
+* **Performance regression detection**: Compare results across builds
+* **Platform optimization**: Identify platform-specific performance characteristics
+* **Ruby version migration**: Analyze performance impact of Ruby upgrades
+
 === Programmatic usage
 
 ==== Basic benchmark execution
@@ -341,11 +1213,14 @@ Tests how quickly libraries can convert Ruby objects into serialized strings.
 
 === Streaming performance
 
-Evaluates streaming event-based parsing performance for libraries that support it, which processes data sequentially and is memory-efficient for large files.
+Evaluates streaming event-based parsing performance for libraries that support
+it, which processes data sequentially and is memory-efficient for large files.
 
 === Memory usage analysis
 
-Profiles memory allocation and retention during serialization operations using the `memory_profiler` gem.
+Profiles memory allocation and retention during serialization operations using
+the `memory_profiler` gem.
+
 
 == Output and reports
 
@@ -381,17 +1256,16 @@ results/
 * **Performance rankings**: Fastest to slowest for each category
 * **Memory profiling**: Detailed memory allocation analysis
 * **Feature matrix**: Capability comparison across libraries
-* **Recommendations**: Use-case specific library suggestions
 * **Environment details**: Ruby version, platform, and library versions
 
 === Sample output
 
-[source]
-----
+[example]
+====
 Serialbench - Comprehensive Serialization Performance Tests
 ===========================================================
 Environment: Ruby 3.3.2 on arm64-darwin23
-Timestamp: 2024-01-15T10:30:00Z
+Timestamp: 2025-06-07T10:30:00Z
 
 Available serializers: rexml, json, oj, toml-rb
 Test formats: xml, json, toml
@@ -409,7 +1283,7 @@ Parsing Performance:
     JSON/json: 12.67ms
     XML/rexml: 28.45ms
     TOML/toml-rb: 35.21ms
-----
+====
 
 == Methodology
 
@@ -443,57 +1317,11 @@ The benchmark suite uses carefully crafted synthetic data that represents common
 * Memory measurements account for garbage collection
 * Results include both absolute and relative performance metrics
 
-== Library comparison matrix
-
-[cols="1,1,1,1,1,1,1"]
-|===
-|Format |Library |Parsing |Generation |Streaming |Memory |Features
-
-|XML |REXML |⭐⭐ |⭐⭐ |⭐⭐⭐ |⭐⭐ |Built-in
-|XML |Ox |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |High-performance
-|XML |Nokogiri |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |Feature-rich
-|XML |LibXML |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |High-performance
-|XML |Oga |⭐⭐ |⭐⭐ |⭐⭐⭐ |⭐⭐ |Pure Ruby
-|JSON |JSON |⭐⭐⭐ |⭐⭐⭐ |❌ |⭐⭐⭐ |Built-in
-|JSON |Oj |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |High-performance
-|JSON |YAJL |⭐⭐⭐⭐ |⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐ |Streaming
-|TOML |TOML-RB |⭐⭐⭐ |⭐⭐⭐ |❌ |⭐⭐⭐ |Standard
-|TOML |Tomlib |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |❌ |⭐⭐⭐⭐⭐ |High-performance
-|===
-
-_Performance ratings: ⭐⭐⭐⭐⭐ Excellent, ⭐⭐⭐⭐ Good, ⭐⭐⭐ Average, ⭐⭐ Below average, ⭐ Poor, ❌ Not supported_
-
-== Recommendations
-
-=== For high-performance JSON applications
-
-**Oj** is recommended for applications where JSON parsing/generation speed is critical. It consistently outperforms the built-in JSON library.
-
-=== For configuration files
-
-**TOML** provides human-readable configuration with good parsing performance. **JSON** is faster but less readable for configuration.
-
-=== For data interchange
-
-**JSON** offers the best balance of performance, compatibility, and tooling support across different systems.
-
-=== For document processing
-
-**XML** with **REXML** provides built-in support, though performance is lower than JSON alternatives.
-
-=== For memory-constrained environments
-
-**Oj** demonstrates superior memory efficiency. For large file processing, streaming approaches are recommended where available.
-
-=== For minimal dependencies
-
-**JSON** and **REXML** are included with Ruby and require no additional gems, making them suitable for environments with strict dependency constraints.
-
 == Development
 
 === Running tests
 
-[source,shell]
+[source]
 ----
 $ bundle exec rake
 $ bundle exec rspec
@@ -501,21 +1329,21 @@ $ bundle exec rspec
 
 === Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin feature/my-new-feature`)
-5. Create a new Pull Request
+. Fork the repository
+. Create your feature branch (`git checkout -b feature/my-new-feature`)
+. Commit your changes (`git commit -am 'Add some feature'`)
+. Push to the branch (`git push origin feature/my-new-feature`)
+. Create a new Pull Request
 
 === Adding new serializers
 
 To add support for additional serialization libraries:
 
-1. Create a new serializer class in `lib/serialbench/serializers/{format}/`
-2. Inherit from the appropriate base class (`BaseXmlSerializer`, `BaseJsonSerializer`, etc.)
-3. Implement the required methods: `parse`, `generate`, `name`, `version`
-4. Add the serializer to the registry in `lib/serialbench/serializers.rb`
-5. Update documentation and tests
+. Create a new serializer class in `lib/serialbench/serializers/{format}/`
+. Inherit from the appropriate base class (`BaseXmlSerializer`, `BaseJsonSerializer`, etc.)
+. Implement the required methods: `parse`, `generate`, `name`, `version`
+. Add the serializer to the registry in `lib/serialbench/serializers.rb`
+. Update documentation and tests
 
 ==== Example: Adding a new JSON serializer