refactor and add ci step for publishing plotly_static

Signed-off-by: Andrei Gherghescu <[email protected]>

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/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: |

.github/workflows/ci.yml

@@ -252,8 +252,6 @@ jobs:
           targets: wasm32-unknown-unknown
       - run: cd ${{ github.workspace }}/examples/wasm-yew/${{ matrix.example }} && cargo build --target wasm32-unknown-unknown
 
-
-
   build_book:
     name: Build Book 
     runs-on: ubuntu-latest
@@ -270,15 +268,6 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
       - run: cargo install mdbook --no-default-features --features search --vers "^0.4" --locked --quiet
       - name: Build examples to generate needed html files
-        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
-          cd ${{ github.workspace }}/examples/themes && cargo run
-          cd ${{ github.workspace }}/examples/static_export && cargo run
+        run: .github/scripts/build-book-examples.sh ${{ github.workspace }}/examples
       - name: Build book 
         run: mdbook build docs/book

.github/workflows/publish_plotly_static.yml

@@ -0,0 +1,22 @@
+name: Publish plotly-static
+
+on:
+  workflow_dispatch:
+
+jobs:
+  create-crates-io-release:
+    name: Deploy to crates.io
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dtolnay/rust-toolchain@stable
+    - name: Setup Chrome (for static_export)
+      uses: browser-actions/setup-chrome@v1
+      with:
+        chrome-version: 'latest'
+        install-chromedriver: true
+    
+    - run: cargo login ${{ env.CRATES_IO_TOKEN }}
+      env:
+        CRATES_IO_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
+    - run: cargo publish --allow-dirty -p plotly_static --features webdriver_downlaod,chromedriver

.github/workflows/release.yml

@@ -15,10 +15,17 @@ jobs:
     - run: cargo login ${{ env.CRATES_IO_TOKEN }}
       env:
         CRATES_IO_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
+    - name: Setup Chrome (for static_export)
+      uses: browser-actions/setup-chrome@v1
+      with:
+        chrome-version: 'latest'
+        install-chromedriver: true        
     - run: cargo publish --allow-dirty -p plotly_derive
     - run: sleep 10
     - run: cargo publish --allow-dirty -p plotly_kaleido
     - run: sleep 10
+    - run: cargo publish --allow-dirty -p plotly_static --features webdriver_downlaod,chromedriver
+    - run: sleep 10
     - run: cargo publish --allow-dirty -p plotly
 
   create-gh-release:

docs/book/src/fundamentals/static_image_export.md

@@ -21,15 +21,15 @@ The static export functionality is controlled by feature flags in the main `plot
 ### Cargo.toml Configuration Examples:
 
 ```toml
-# Basic usage with manual WebDriver installation
+# Basic usage with manual Chromedriver installation
 [dependencies]
 plotly = { version = "0.13", features = ["static_export_chromedriver"] }
 
-# With automatic WebDriver download
+# With automatic Chromedriver download
 [dependencies]
 plotly = { version = "0.13", features = ["static_export_chromedriver", "static_export_wd_download"] }
 
-# Recommended: Default configuration with Firefox + auto-download
+# Recommended: Default configuration with Chromedriver + auto-download
 [dependencies]
 plotly = { version = "0.13", features = ["static_export_default"] }
 ```
@@ -43,9 +43,13 @@ plotly = { version = "0.13", features = ["static_export_default"] }
 
 2. **Browser Installation**: You need Chrome/Chromium or Firefox installed
 
-3. **Environment Variable** (optional): Set `WEBDRIVER_PATH` to specify custom WebDriver binary location (should point to the full executable path)
+3. **Environment Variables** (optional): 
+   - Set `WEBDRIVER_PATH` to specify custom WebDriver binary location (should point to the full executable path)
+   - Set `BROWSER_PATH` to specify custom browser binary location (should point to the full executable path)
+   
    ```bash
    export WEBDRIVER_PATH=/path/to/chromedriver
+   export BROWSER_PATH=/path/to/chrome
    ```
 
 ## Basic Usage

examples/custom_controls/src/main.rs

@@ -426,7 +426,7 @@ fn main() {
     bar_chart_with_modifiable_bar_mode(false, "bar_chart");
 
     // Silder examples
-    bar_chart_with_slider_customization(true, "bar_chart_with_slider_customization");
+    bar_chart_with_slider_customization(false, "bar_chart_with_slider_customization");
     sinusoidal_slider_example(false, "sinusoidal_slider_example");
     gdp_life_expectancy_slider_example(false, "gdp_life_expectancy_slider_example");
 }

examples/kaleido/src/main.rs

@@ -17,12 +17,15 @@ fn main() {
     // The image will be saved to format!("output/image.{image_format}") relative to
     // the current working directory.
     #[allow(deprecated)]
-    plot.write_image(&filename, ImageFormat::EPS, width, height, scale);
-    plot.write_image(&filename, ImageFormat::JPEG, width, height, scale);
-    plot.write_image(&filename, ImageFormat::PDF, width, height, scale);
-    plot.write_image(&filename, ImageFormat::PNG, width, height, scale);
-    plot.write_image(&filename, ImageFormat::SVG, width, height, scale);
-    plot.write_image(&filename, ImageFormat::WEBP, width, height, scale);
+    {
+        plot.write_image(&filename, ImageFormat::EPS, width, height, scale);
+        plot.write_image(&filename, ImageFormat::JPEG, width, height, scale);
+        plot.write_image(&filename, ImageFormat::PDF, width, height, scale);
+        plot.write_image(&filename, ImageFormat::PNG, width, height, scale);
+        plot.write_image(&filename, ImageFormat::SVG, width, height, scale);
+        plot.write_image(&filename, ImageFormat::WEBP, width, height, scale);
 
-    let _svg_string = plot.to_svg(width, height, scale);
+        let svg_string = plot.to_svg(width, height, scale);
+        println!("SVG plot string: {svg_string}");
+    }
 }

examples/static_export/README.md

@@ -1,24 +1,29 @@
 # Static Export Example
 
-This example demonstrates how to use the `plotly_static` crate for exporting Plotly plots to static images using WebDriver and headless browsers. See also the `Static Image Export` section in the book for a more detailed description.
+This example demonstrates how to use the `plotly_static` crate for exporting Plotly plots to static images.
+
+The `plotly_static` provides a interface for converting Plotly plots into various static image formats (PNG, JPEG, WEBP, SVG, PDF) using WebDriver and headless browsers.
+
+In this example it is shown how to use the `StaticExporter` with the old style Kaleido API and also with the new style API. Using the former API is fine for one time static exports, but that API will crate an instance of the `StaticExporter` for each `write_image` call. The new style API is recommended for performance as the same instance of the `StaticExporter` can be reused accross mutliple exports.  
+
+See also the `Static Image Export` section in the book for a more detailed description.
 
 ## Overview
 
-The `plotly_static` crate provides a high-level interface for converting Plotly JSON plots into various static image formats (PNG, JPEG, WEBP, SVG, PDF) using WebDriver and headless browsers.
 
-## Features Demonstrated
+## Features 
 
 - **Multiple Export Formats**: PNG, JPEG, SVG, PDF
-- **Exporter Reuse**: Efficient reuse of a single `StaticExporter` instance
+- **Exporter Reuse (new API)**: Efficient reuse of a single `StaticExporter` instance
 - **String Export**: Base64 and SVG string output for web applications
 - **Logging**: Debug information and progress monitoring
-- **Error Handling**: Proper error handling with `Result` types
+- **Error Handling**: Error handling with `Result` types
 
 ## Prerequisites
 
 1. **Browser Installation**: You need either Firefox (for geckodriver) or Chrome/Chromium (for chromedriver)
-2. **WebDriver**: Automatically downloaded with the `static_export_default` feature
-3. **Internet Connection**: Required for initial WebDriver download (if using `webdriver_download` feature)
+2. **WebDriver**: Chromedriver automatically downloaded with the `static_export_default` feature
+3. **Internet Connection**: Required for WebDriver download (if using `webdriver_download` feature)
 
 ## Feature Flags
 
@@ -30,13 +35,13 @@ The example uses `static_export_default` which includes:
 ### Alternative Configurations
 
 ```toml
-# Use Chrome/Chromium instead of Firefox
-plotly = { version = "0.13", features = ["static_export_chromedriver", "static_export_wd_download"] }
+# Use Firefox instead of Chrome/Chromium 
+plotly = { version = "0.13", features = ["static_export_geckodriver", "static_export_wd_download"] }
 
-# Manual WebDriver installation (no automatic download)
+# Manual Geckodriver installation (no automatic download)
 plotly = { version = "0.13", features = ["static_export_geckodriver"] }
 
-# Chrome with manual installation
+# Manual Chromedriver installation (no automatic download)
 plotly = { version = "0.13", features = ["static_export_chromedriver"] }
 ```
 
@@ -50,7 +55,7 @@ cargo run
 RUST_LOG=debug cargo run
 
 # With custom WebDriver path
-WEBDRIVER_PATH=/path/to/geckodriver cargo run
+WEBDRIVER_PATH=/path/to/chromedriver cargo run
 ```
 
 ## Output
@@ -61,17 +66,11 @@ The example generates several files:
 - `plot3.svg`: Vector format, scalable, good for web
 - `plot1.pdf`: Vector format, good for printing
 
-## Performance Tips
-
-1. **Reuse Exporters**: Create a single `StaticExporter` and reuse it for multiple plots
-2. **Parallel Usage**: Use unique ports for parallel operations (tests, etc.)
-3. **Resource Management**: The exporter automatically manages WebDriver lifecycle
-
 ## Advanced Configuration
 
 The example includes commented code showing advanced configuration options:
 - Custom WebDriver ports for parallel usage
-- Offline mode for bundled JavaScript
+- Offline mode for bundled JavaScript 
 - Custom browser capabilities
 - Explicit WebDriver spawning
 
@@ -81,11 +80,10 @@ The example includes commented code showing advanced configuration options:
 
 1. **WebDriver not found**: Ensure the browser is installed and WebDriver is available
 2. **Port conflicts**: Use unique ports for parallel operations
-3. **Permission errors**: Ensure WebDriver has execute permissions
 
 ### Debug Information
 
-Set `RUST_LOG=debug` to see detailed WebDriver operations and troubleshooting information.
+Set `RUST_LOG=debug` or`RUST_LOG=trace`to see detailed WebDriver operations and troubleshooting information.
 
 ## Related Documentation