add static export functionality with WebDriver

Add static export functionality using WebDriver to control a host
browser.
 - allow user to reuse the exporter object but also keep the old style
   Kaleido API
 - allow user to set browser capabilities via setter
 - allow user to configure html2pdf timeout
 - use data uri for CDN case and file for offline case when generating the html for static image export
     - there are size restrictions when using data-uri , webdriver cannot load large data-uri
       files, so for offline mode, default to using html returned by to_file
 - use build.rs to download webdriver chromedriver/geckodriver
 - contains documentation and add example for plotly_static
 - include an example on how to use static export for json data

 - refactored usage of imageformat between packages: plotly,
   plotly_kaleido, plotly_static

 - the new static export is included in the plotly crate as default and kaleido is marked as
   deprecated using deprecation warnings
 - added custom CI setup for Windows as Windows GitHub Action with Chrome setup is unique
 - expand ci with Firefox + Ubuntu for plotly_static
 - add ci step for publishing plotly_static

Signed-off-by: Andrei Gherghescu <8067229+andrei-ng@users.noreply.github.com>

Author: andrei-ng

.github/scripts/build-book-examples.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+
+# Script to build examples needed for book artifacts
+# This script is used by both the CI build_book job and the book.yml workflow
+
+# Note: static_export example requires Chrome setup for WebDriver functionality
+# The CI jobs set up Chrome, while when running locally, you may need to setup 
+# your browser and webdriver manually to ensure this example works properly.
+
+set -e  # Exit on any error
+
+# Function to display usage
+usage() {
+    echo "Usage: $0 <examples_directory>"
+    echo "  examples_directory: Path to the examples directory (e.g., examples or \$GITHUB_WORKSPACE/examples)"
+    echo ""
+    echo "This script builds all examples needed for the book documentation."
+    exit 1
+}
+
+# Check if examples directory is provided
+if [ $# -ne 1 ]; then
+    usage
+fi
+
+EXAMPLES_DIR="$1"
+
+# Validate that the examples directory exists
+if [ ! -d "$EXAMPLES_DIR" ]; then
+    echo "Error: Examples directory '$EXAMPLES_DIR' does not exist"
+    exit 1
+fi
+
+echo "Building examples for book artifacts from: $EXAMPLES_DIR"
+
+# List of examples needed for the book, sorted alphabetically
+# These examples generate HTML files that are included in the book documentation
+BOOK_EXAMPLES=(
+    "3d_charts"
+    "basic_charts"
+    "custom_controls"
+    "financial_charts"
+    "scientific_charts"
+    "shapes"
+    "static_export"
+    "statistical_charts"
+    "subplots"
+    "themes"
+)
+
+# Build each example
+for example in "${BOOK_EXAMPLES[@]}"; do
+    example_path="$EXAMPLES_DIR/$example"
+    
+    if [ ! -d "$example_path" ]; then
+        echo "Warning: Example directory '$example_path' does not exist, skipping..."
+        continue
+    fi
+    
+    echo "Building $example example..."
+    cd "$example_path"
+    
+    # Check if Cargo.toml exists
+    if [ ! -f "Cargo.toml" ]; then
+        echo "Warning: No Cargo.toml found in $example_path, skipping..."
+        cd - > /dev/null
+        continue
+    fi
+    
+    # Run the example
+    if cargo run; then
+        echo "✓ Successfully built $example"
+    else
+        echo "✗ Failed to build $example"
+        exit 1
+    fi
+    
+    # Return to the original directory
+    cd - > /dev/null
+done
+
+echo "All examples built successfully!"

.github/scripts/setup-windows-static-export.ps1

@@ -0,0 +1,104 @@
+# Windows environment setup for plotly static export tests
+# This script sets up Chrome, chromedriver, and environment variables for Windows CI
+
+param(
+    [string]$ChromeVersion,
+    [string]$ChromePath,
+    [string]$ChromeDriverPath
+)
+
+Write-Host "=== Setting up Windows environment for static export ==="
+
+# Find chromedriver path
+$chromedriverPath = $ChromeDriverPath
+if (-not (Test-Path $chromedriverPath)) {
+    Write-Host "Action output chromedriver path not found, searching for alternatives..."
+
+    $commonPaths = @(
+        "C:\Program Files\Google\Chrome\Application\chromedriver.exe",
+        "C:\Program Files (x86)\Google\Chrome\Application\chromedriver.exe",
+        "$env:USERPROFILE\AppData\Local\Google\Chrome\Application\chromedriver.exe",
+        "$env:PROGRAMFILES\Google\Chrome\Application\chromedriver.exe",
+        "$env:PROGRAMFILES(X86)\Google\Chrome\Application\chromedriver.exe"
+    )
+
+    foreach ($path in $commonPaths) {
+        if (Test-Path $path) {
+            Write-Host "Using chromedriver from: $path"
+            $chromedriverPath = $path
+            break
+        }
+    }
+}
+
+# Find Chrome path
+$chromePath = $ChromePath
+if (-not (Test-Path $chromePath)) {
+    # Try the tool cache path first
+    $toolCachePath = "C:\hostedtoolcache\windows\setup-chrome\chromium\$ChromeVersion\x64\chrome.exe"
+    if (Test-Path $toolCachePath) {
+        $chromePath = $toolCachePath
+        Write-Host "Using Chrome from setup-chrome installation: $chromePath"
+    } else {
+        # Fallback: search for Chrome in the tool cache
+        $toolCacheDir = "C:\hostedtoolcache\windows\setup-chrome\chromium"
+        if (Test-Path $toolCacheDir) {
+            $chromeExe = Get-ChildItem -Path $toolCacheDir -Recurse -Name "chrome.exe" | Select-Object -First 1
+            if ($chromeExe) {
+                $chromePath = Join-Path $toolCacheDir $chromeExe
+                Write-Host "Using Chrome from tool cache search: $chromePath"
+            } else {
+                $chromePath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
+                Write-Host "Using system Chrome: $chromePath"
+            }
+        } else {
+            $chromePath = "C:\Program Files\Google\Chrome\Application\chrome.exe"
+            Write-Host "Using system Chrome: $chromePath"
+        }
+    }
+}
+
+# Set environment variables
+$env:WEBDRIVER_PATH = $chromedriverPath
+$env:BROWSER_PATH = $chromePath
+$env:RUST_LOG = "debug"
+$env:RUST_BACKTRACE = "1"
+$env:ANGLE_DEFAULT_PLATFORM = "swiftshader"
+
+Write-Host "Environment variables set:"
+Write-Host "WEBDRIVER_PATH: $env:WEBDRIVER_PATH"
+Write-Host "BROWSER_PATH: $env:BROWSER_PATH"
+Write-Host "RUST_LOG: $env:RUST_LOG"
+Write-Host "RUST_BACKTRACE: $env:RUST_BACKTRACE"
+
+# Verify paths exist
+if (-not (Test-Path $env:WEBDRIVER_PATH)) {
+    Write-Error "Chromedriver executable not found at: $env:WEBDRIVER_PATH"
+    Write-Host "Available chromedriver locations:"
+    Get-ChildItem -Path "C:\Program Files\Google\Chrome\Application\" -Name "chromedriver*" -ErrorAction SilentlyContinue
+    Get-ChildItem -Path "C:\Program Files (x86)\Google\Chrome\Application\" -Name "chromedriver*" -ErrorAction SilentlyContinue
+    exit 1
+}
+
+if (-not (Test-Path $env:BROWSER_PATH)) {
+    Write-Error "Chrome not found at: $env:BROWSER_PATH"
+    exit 1
+}
+
+# Test Chrome version
+try {
+    $chromeVersion = & "$env:BROWSER_PATH" --version 2>&1
+    Write-Host "Chrome version: $chromeVersion"
+} catch {
+    Write-Host "Failed to get Chrome version: $_"
+}
+
+# Test chromedriver version
+try {
+    $chromedriverVersion = & "$env:WEBDRIVER_PATH" --version 2>&1
+    Write-Host "Chromedriver version: $chromedriverVersion"
+} catch {
+    Write-Host "Failed to get chromedriver version: $_"
+}
+
+Write-Host "=== Windows environment setup completed ==="

.github/workflows/book.yml

@@ -15,16 +15,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Setup Chrome (for static_export)
+        uses: browser-actions/setup-chrome@v1
+        with:
+          chrome-version: 'latest'
+          install-chromedriver: true
       - run: cargo install mdbook --no-default-features --features search --vers "^0.4" --locked --quiet
       - name: Build examples
-        run: |
-          cd ${{ github.workspace }}/examples/basic_charts && cargo run
-          cd ${{ github.workspace }}/examples/statistical_charts && cargo run
-          cd ${{ github.workspace }}/examples/scientific_charts && cargo run
-          cd ${{ github.workspace }}/examples/financial_charts && cargo run
-          cd ${{ github.workspace }}/examples/3d_charts && cargo run
-          cd ${{ github.workspace }}/examples/subplots && cargo run
-          cd ${{ github.workspace }}/examples/shapes && cargo run
+        run: .github/scripts/build-book-examples.sh ${{ github.workspace }}/examples
       - run: mdbook build docs/book
       - name: Checkout gh-pages branch
         run: |