improve documentation and add example for static_export

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

Author: andrei-ng

README.md

@@ -108,7 +108,32 @@ When the applications developed with `plotly.rs` are intended for other targets
 
 Kaleido binaries are available on Github [release page](https://github.com/plotly/Kaleido/releases). It currently supports Linux(`x86_64`), Windows(`x86_64`) and MacOS(`x86_64`/`aarch64`).
 
-## Exporting a Static Images
+## Exporting Static Images with plotly_static (Recommended)
+
+The recommended way to export static images is using the `plotly_static` backend, which uses a headless browser via WebDriver (Chrome or Firefox) for rendering. This is available via the `static_export_default` feature:
+
+```toml
+[dependencies]
+plotly = { version = "0.12", features = ["static_export_default"] }
+```
+
+This supports PNG, JPEG, WEBP, SVG, and PDF formats:
+
+```rust
+use plotly::{Plot, Scatter, ImageFormat};
+
+let mut plot = Plot::new();
+plot.add_trace(Scatter::new(vec![0, 1, 2], vec![2, 1, 0]));
+
+plot.write_image("out.png", ImageFormat::PNG, 800, 600, 1.0)?;
+plot.write_image("out.svg", ImageFormat::SVG, 800, 600, 1.0)?;
+let base64_data = plot.to_base64(ImageFormat::PNG, 800, 600, 1.0)?;
+let svg_string = plot.to_svg(800, 600, 1.0)?;
+```
+
+**Note:** This feature requires a WebDriver-compatible browser (Chrome or Firefox) as well as a Webdriver (chromedriver/geckodriver) to be available on the system. For advanced usage, see the [`plotly_static` crate documentation](https://docs.rs/plotly_static/).
+
+## Exporting Static Images with Kaleido (to be deprecated)
 
 Enable the `kaleido` feature and opt in for automatic downloading of the `kaleido` binaries by doing the following
 

docs/book/src/SUMMARY.md

@@ -7,6 +7,7 @@
     - [ndarray Support](./fundamentals/ndarray_support.md)
     - [Shapes](./fundamentals/shapes.md)
     - [Themes](./fundamentals/themes.md)
+    - [Static Image Export](./fundamentals/static_image_export.md)
 - [Recipes](./recipes.md)
     - [Basic Charts](./recipes/basic_charts.md)
         - [Scatter Plots](./recipes/basic_charts/scatter_plots.md)

docs/book/src/fundamentals.md

@@ -18,4 +18,12 @@
 
 # Fundamentals
 
-Functionality that applies to the library as a whole is described in the next sections.
+Functionality that applies to the library as a whole is described in the next sections.
+
+## Core Features
+
+- **[Jupyter Support](./fundamentals/jupyter_support.md)**: Interactive plotting in Jupyter notebooks
+- **[ndarray Support](./fundamentals/ndarray_support.md)**: Integration with the ndarray crate for numerical computing
+- **[Shapes](./fundamentals/shapes.md)**: Adding shapes and annotations to plots
+- **[Themes](./fundamentals/themes.md)**: Customizing plot appearance with themes
+- **[Static Image Export](./fundamentals/static_image_export.md)**: Exporting plots to static images (PNG, JPEG, SVG, PDF) using WebDriver

docs/book/src/fundamentals/static_image_export.md

@@ -1 +1,226 @@
 # Static Image Export
+
+The `plotly` crate provides static image export functionality through the `plotly_static` crate, which uses WebDriver and headless browsers to render plots as static images.
+
+## Overview
+
+Static image export allows you to convert Plotly plots into various image formats (PNG, JPEG, WEBP, SVG, PDF) for use in reports, web applications, or any scenario where you need static images.
+
+## Feature Flags
+
+The static export functionality is controlled by feature flags in the main `plotly` crate:
+
+### Required Features (choose one):
+- `static_export_chromedriver`: Uses Chrome/Chromium for rendering (requires chromedriver)
+- `static_export_geckodriver`: Uses Firefox for rendering (requires geckodriver)
+
+### Optional Features:
+- `static_export_downloader`: Automatically downloads WebDriver binaries at build time
+- `static_export_default`: Convenience feature that includes geckodriver + downloader
+
+### Cargo.toml Configuration Examples:
+
+```toml
+# Basic usage with manual WebDriver installation
+[dependencies]
+plotly = { version = "0.12", features = ["static_export_chromedriver"] }
+
+# With automatic WebDriver download
+[dependencies]
+plotly = { version = "0.12", features = ["static_export_chromedriver", "static_export_downloader"] }
+
+# Recommended: Default configuration with Firefox + auto-download
+[dependencies]
+plotly = { version = "0.12", features = ["static_export_default"] }
+```
+
+## Prerequisites
+
+1. **WebDriver Installation**: You need either chromedriver or geckodriver installed
+   - Chrome: Download from https://chromedriver.chromium.org/
+   - Firefox: Download from https://github.com/mozilla/geckodriver/releases
+   - Or use the `static_export_downloader` feature for automatic download
+
+2. **Browser Installation**: You need Chrome/Chromium or Firefox installed
+
+3. **Environment Variable** (optional): Set `WEBDRIVER_PATH` to specify custom WebDriver location
+   ```bash
+   export WEBDRIVER_PATH=/path/to/chromedriver
+   ```
+
+## Basic Usage
+
+### Simple Export
+
+```rust
+use plotly::{Plot, Scatter};
+use plotly::plotly_static::ImageFormat;
+
+let mut plot = Plot::new();
+plot.add_trace(Scatter::new(vec![1, 2, 3], vec![4, 5, 6]));
+
+// Export to PNG file
+plot.write_image("my_plot", ImageFormat::PNG, 800, 600, 1.0)
+    .expect("Failed to export plot");
+```
+
+### Efficient Exporter Reuse
+
+For better performance when exporting multiple plots, reuse a single `StaticExporter`:
+
+```rust
+use plotly::{Plot, Scatter};
+use plotly::plotly_static::{StaticExporterBuilder, ImageFormat};
+
+let mut plot1 = Plot::new();
+plot1.add_trace(Scatter::new(vec![1, 2, 3], vec![4, 5, 6]));
+
+let mut plot2 = Plot::new();
+plot2.add_trace(Scatter::new(vec![2, 3, 4], vec![5, 6, 7]));
+
+// Create a single exporter to reuse
+let mut exporter = StaticExporterBuilder::default()
+    .build()
+    .expect("Failed to create StaticExporter");
+
+// Export multiple plots using the same exporter
+plot1.write_image_with_exporter(&mut exporter, "plot1", ImageFormat::PNG, 800, 600, 1.0)
+    .expect("Failed to export plot1");
+plot2.write_image_with_exporter(&mut exporter, "plot2", ImageFormat::JPEG, 800, 600, 1.0)
+    .expect("Failed to export plot2");
+```
+
+## Supported Formats
+
+### Raster Formats
+- **PNG**: Portable Network Graphics, lossless compression
+- **JPEG**: Joint Photographic Experts Group, lossy compression (smaller files)
+- **WEBP**: Google's image format
+
+### Vector Formats
+- **SVG**: Scalable Vector Graphics
+- **PDF**: Portable Document Format
+
+### Deprecated
+- **EPS**: Encapsulated PostScript (will be removed in version 0.14.0)
+
+## String Export
+
+For web applications or APIs, you can export to strings:
+
+```rust
+use plotly::{Plot, Scatter};
+use plotly::plotly_static::{StaticExporterBuilder, ImageFormat};
+
+let mut plot = Plot::new();
+plot.add_trace(Scatter::new(vec![1, 2, 3], vec![4, 5, 6]));
+
+let mut exporter = StaticExporterBuilder::default()
+    .build()
+    .expect("Failed to create StaticExporter");
+
+// Get base64 data (useful for embedding in HTML)
+let base64_data = plot.to_base64_with_exporter(&mut exporter, ImageFormat::PNG, 400, 300, 1.0)
+    .expect("Failed to export plot");
+
+// Get SVG data (vector format, scalable)
+let svg_data = plot.to_svg_with_exporter(&mut exporter, 400, 300, 1.0)
+    .expect("Failed to export plot");
+```
+
+## Advanced Configuration
+
+### Custom WebDriver Configuration
+
+```rust
+use plotly::plotly_static::StaticExporterBuilder;
+
+let mut exporter = StaticExporterBuilder::default()
+    .webdriver_port(4445)  // Use different port for parallel operations
+    .spawn_webdriver(true) // Explicitly spawn WebDriver
+    .offline_mode(true)    // Use bundled JavaScript (no internet required)
+    .webdriver_browser_caps(vec![
+        "--headless".to_string(),
+        "--no-sandbox".to_string(),
+        "--disable-gpu".to_string(),
+        "--disable-dev-shm-usage".to_string(),
+    ])
+    .build()
+    .expect("Failed to create StaticExporter");
+```
+
+### Parallel Usage
+
+For parallel operations (tests, etc.), use unique ports:
+
+```rust
+use plotly::plotly_static::StaticExporterBuilder;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+// Generate unique ports for parallel usage
+static PORT_COUNTER: AtomicU32 = AtomicU32::new(4444);
+
+fn get_unique_port() -> u32 {
+    PORT_COUNTER.fetch_add(1, Ordering::SeqCst)
+}
+
+// Each thread/process should use a unique port
+let mut exporter = StaticExporterBuilder::default()
+    .webdriver_port(get_unique_port())
+    .build()
+    .expect("Failed to build StaticExporter");
+```
+
+## Logging Support
+
+Enable logging for debugging and monitoring:
+
+```rust
+use plotly::plotly_static::StaticExporterBuilder;
+
+// Initialize logging (typically done once at the start of your application)
+env_logger::init();
+
+// Set log level via environment variable
+// RUST_LOG=debug cargo run
+
+let mut exporter = StaticExporterBuilder::default()
+    .build()
+    .expect("Failed to create StaticExporter");
+```
+
+## Performance Considerations
+
+- **Exporter Reuse**: Create a single `StaticExporter` and reuse it for multiple plots
+- **Parallel Usage**: Use unique ports for parallel operations (tests, etc.)
+- **Resource Management**: The exporter automatically manages WebDriver lifecycle
+- **Format Selection**: Choose appropriate formats for your use case:
+  - PNG: Good quality, lossless
+  - JPEG: Smaller files, lossy
+  - SVG: Scalable, good for web
+  - PDF: Good for printing
+
+## Complete Example
+
+See the [static export example](../../../examples/static_export/) for a complete working example that demonstrates:
+
+- Multiple export formats
+- Exporter reuse
+- String export
+- Logging
+- Error handling
+
+To run the example:
+
+```bash
+cd examples/static_export
+cargo run
+```
+**NOTE** Set `RUST_LOG=debug` to see detailed WebDriver operations and troubleshooting information.
+
+## Related Documentation
+
+- [plotly_static crate documentation](https://docs.rs/plotly_static/)
+- [WebDriver specification](https://w3c.github.io/webdriver/)
+- [GeckoDriver documentation](https://firefox-source-docs.mozilla.org/testing/geckodriver/)
+- [ChromeDriver documentation](https://chromedriver.chromium.org/)

examples/custom_controls/src/main.rs

@@ -280,7 +280,7 @@ fn sinusoidal_slider_example(show: bool, file_name: &str) {
                 Visible::False
             }) // Make 10th trace visible
             .line(plotly::common::Line::new().color("#00CED1").width(6.0))
-            .name(format!("ν = {:.1}", frequency));
+            .name(format!("ν = {frequency:.1}"));
         plot.add_trace(trace);
     }
 
@@ -291,12 +291,11 @@ fn sinusoidal_slider_example(show: bool, file_name: &str) {
         let mut visible = vec![Visible::False; num_steps];
         visible[i] = Visible::True;
         let step = SliderStepBuilder::new()
-            .label(format!("step-{}", i))
-            .value(format!("{:.1}", frequency))
+            .label(format!("step-{i}"))
+            .value(format!("{frequency:.1}"))
             .push_restyle(Scatter::<f64, f64>::modify_visible(visible))
             .push_relayout(Layout::modify_title(format!(
-                "Slider switched to step: {}",
-                i
+                "Slider switched to step: {i}"
             )))
             .build()
             .unwrap();
@@ -389,12 +388,11 @@ fn gdp_life_expectancy_slider_example(show: bool, file_name: &str) {
             visible[start..end].fill(Visible::True);
 
             SliderStepBuilder::new()
-                .label(format!("year = {}", year))
+                .label(format!("year = {year}"))
                 .value(year)
                 .push_restyle(Scatter::<f64, f64>::modify_visible(visible))
                 .push_relayout(Layout::modify_title(format!(
-                    "GDP vs. Life Expectancy ({})",
-                    year
+                    "GDP vs. Life Expectancy ({year})"
                 )))
                 .build()
                 .unwrap()

examples/customization/src/main.rs

@@ -49,7 +49,7 @@ fn multiple_plots_on_same_html_page(show: bool, file_name: &str) {
         .to_html_string();
 
     std::fs::create_dir_all("./output").unwrap();
-    let path = format!("./output/inline_{}.html", file_name);
+    let path = format!("./output/inline_{file_name}.html");
     let mut file = File::create(&path).unwrap();
     file.write_all(html.as_bytes())
         .expect("failed to write html output");

examples/plotly_utils/src/lib.rs

@@ -18,10 +18,10 @@ pub fn write_example_to_html(plot: &Plot, name: &str) -> String {
     std::fs::create_dir_all("./output").unwrap();
     // Write inline HTML
     let html = plot.to_inline_html(Some(name));
-    let path = format!("./output/inline_{}.html", name);
+    let path = format!("./output/inline_{name}.html");
     std::fs::write(path, html).unwrap();
     // Write standalone HTML
-    let path = format!("./output/{}.html", name);
+    let path = format!("./output/{name}.html");
     plot.write_html(&path);
     path
 }

examples/static_export_example/Cargo.toml examples/static_export/Cargo.tomlexamples/static_export_example/Cargo.toml renamed to examples/static_export/Cargo.toml

@@ -3,8 +3,10 @@ name = "static_export_example"
 version = "0.1.0"
 authors = ["Andrei Gherghescu [email protected]"]
 edition = "2021"
+description = "Example demonstrating static image export using plotly_static with WebDriver"
+readme = "README.md"
 
 [dependencies]
 plotly = { path = "../../plotly", features = ["static_export_default"] }
 env_logger = "0.10"
-log = "0.4" 
+log = "0.4"