refactor examples and add themes example to mdbook

andrei-ng · andrei-ng · commit b874b808cb10 · 2025-06-19T20:15:15.000+01:00
Signed-off-by: Andrei Gherghescu &lt;8067229+andrei-ng@users.noreply.github.com&gt;
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -29,3 +29,4 @@
     - [Subplots](./recipes/subplots.md)
         - [Subplots](./recipes/subplots/subplots.md)
         - [Multiple Axes](./recipes/subplots/multiple_axes.md)
+    - [Themes](./recipes/themes.md)
diff --git a/docs/book/src/recipes/themes.md b/docs/book/src/recipes/themes.md
@@ -0,0 +1,66 @@
+# Themes
+
+The complete source code for the following examples can also be found [here](https://github.com/plotly/plotly.rs/tree/main/examples/themes).
+
+# Use different theme templates
+
+Similar to [Plotly Python templates](https://plotly.com/python/templates/), plotly.rs provides several built-in themes that can be applied to your plots.
+
+```rust,no_run
+use plotly::{
+    common::{Marker, Mode, Title},
+    layout::{Layout, BuiltinTheme},
+    Plot, Scatter,
+};
+```
+
+The `to_inline_html` method is used to produce the html plot displayed in this page.
+
+## Default Theme (Plotly)
+
+{{#include ../../../../examples/themes/output/inline_gapminder_plotly.html}}
+
+## Plotly White Theme
+
+{{#include ../../../../examples/themes/output/inline_gapminder_plotly_white.html}}
+
+## Plotly Dark Theme
+
+{{#include ../../../../examples/themes/output/inline_gapminder_plotly_dark.html}}
+
+## Seaborn Theme
+
+{{#include ../../../../examples/themes/output/inline_gapminder_seaborn.html}}
+
+## Matplotlib Theme
+
+{{#include ../../../../examples/themes/output/inline_gapminder_matplotlib.html}}
+
+## Plotnine Theme
+
+{{#include ../../../../examples/themes/output/inline_gapminder_plotnine.html}}
+
+## Available Themes
+
+The following built-in themes are available in plotly.rs:
+
+- `BuiltinTheme::Default` - Default Plotly theme
+- `BuiltinTheme::PlotlyWhite` - Clean white background theme
+- `BuiltinTheme::PlotlyDark` - Dark theme
+- `BuiltinTheme::Seaborn` - Seaborn-style theme
+- `BuiltinTheme::SeabornWhitegrid` - Seaborn with white grid
+- `BuiltinTheme::SeabornDark` - Dark Seaborn theme
+- `BuiltinTheme::Matplotlib` - Matplotlib-style theme
+- `BuiltinTheme::Plotnine` - Plotnine-style theme
+
+## Using Themes
+
+To apply a theme to your plot, use the `template()` method on the layout:
+
+```rust
+let theme = BuiltinTheme::Seaborn;
+let layout = Layout::new().template(theme.build());
+plot.set_layout(layout);
+```
+
+The example above uses real Gapminder 2007 data showing the relationship between GDP per capita, life expectancy, and population size across different continents, with marker sizes representing population and colors representing continents.
diff --git a/examples/3d_charts/Cargo.toml b/examples/3d_charts/Cargo.toml
@@ -8,3 +8,4 @@ edition = "2021"
 ndarray = "0.16"
 rand = "0.9"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
diff --git a/examples/3d_charts/src/main.rs b/examples/3d_charts/src/main.rs
@@ -1,6 +1,7 @@
 #![allow(dead_code)]
 
 use ndarray::Array;
+use plotly_utils::write_example_to_html;
 use plotly::{
     color::Rgb,
     common::{ColorBar, ColorScale, ColorScalePalette, Font, Marker, MarkerSymbol, Mode},
@@ -259,17 +260,6 @@ fn colorscale_plot(show: bool, file_name: &str) {
 }
 // ANCHOR_END: colorscale_plot
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/Cargo.toml b/examples/Cargo.toml
@@ -1,4 +1,4 @@
 [workspace]
-members = ["*"]
+members = ["*", "plotly_utils"]
 resolver = "2"
 exclude = ["jupyter", "target", "wasm-yew"]
diff --git a/examples/basic_charts/Cargo.toml b/examples/basic_charts/Cargo.toml
@@ -7,5 +7,6 @@ edition = "2021"
 [dependencies]
 ndarray = "0.16"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
 rand = "0.9"
 rand_distr = "0.5"
diff --git a/examples/basic_charts/src/main.rs b/examples/basic_charts/src/main.rs
@@ -15,6 +15,7 @@ use plotly::{
     traces::table::{Cells, Header},
     Bar, Pie, Plot, Sankey, Scatter, ScatterPolar, Table,
 };
+use plotly_utils::write_example_to_html;
 use rand_distr::{Distribution, Normal, Uniform};
 
 // Scatter Plots
@@ -996,18 +997,6 @@ fn grouped_donout_pie_charts(show: bool, file_name: &str) {
 }
 // ANCHOR_END: grouped_donout_pie_charts
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
-
 fn main() {
     // Change false to true on any of these lines to display the example.
 
diff --git a/examples/custom_controls/Cargo.toml b/examples/custom_controls/Cargo.toml
@@ -7,3 +7,4 @@ edition = "2021"
 [dependencies]
 itertools = "0.10"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
diff --git a/examples/custom_controls/src/main.rs b/examples/custom_controls/src/main.rs
@@ -1,6 +1,7 @@
 #![allow(dead_code)]
 
 use itertools::Itertools;
+use plotly_utils::write_example_to_html;
 use plotly::{
     common::{Anchor, ColorScalePalette, Visible},
     layout::{
@@ -117,17 +118,6 @@ fn bar_chart_with_modifiable_bar_mode(show: bool, file_name: &str) {
 }
 // ANCHOR_END: colorscale_plot
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/customization/Cargo.toml b/examples/customization/Cargo.toml
@@ -9,3 +9,4 @@ build_html = "2.5.0"
 rand = "0.9"
 ndarray = "0.16"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
diff --git a/examples/customization/src/main.rs b/examples/customization/src/main.rs
@@ -4,6 +4,7 @@ use std::fs::File;
 use std::io::Write;
 
 use build_html::*;
+use plotly_utils::write_example_to_html;
 use ndarray::Array;
 use plotly::{
     color::NamedColor,
@@ -130,17 +131,6 @@ fn show_with_default_app(temp_path: &str) {
         .expect(DEFAULT_HTML_APP_NOT_FOUND);
 }
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Switch the boolean flag to `true` to display the example, otherwise manually
diff --git a/examples/financial_charts/Cargo.toml b/examples/financial_charts/Cargo.toml
@@ -7,4 +7,5 @@ edition = "2021"
 [dependencies]
 csv = "1.1"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
 serde = "1.0"
diff --git a/examples/financial_charts/src/main.rs b/examples/financial_charts/src/main.rs
@@ -4,6 +4,7 @@ use std::env;
 use std::path::PathBuf;
 
 use plotly::common::TickFormatStop;
+use plotly_utils::write_example_to_html;
 use plotly::layout::{Axis, RangeSelector, RangeSlider, SelectorButton, SelectorStep, StepMode};
 use plotly::{Candlestick, Layout, Ohlc, Plot, Scatter};
 use serde::Deserialize;
@@ -319,17 +320,6 @@ fn simple_ohlc_chart(show: bool, file_name: &str) {
 }
 // ANCHOR_END: simple_ohlc_chart
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/images/src/main.rs b/examples/images/src/main.rs
@@ -2,6 +2,7 @@
 
 use ndarray::arr2;
 use plotly::{color::Rgb, image::ColorModel, Image, Plot};
+use plotly_utils::write_example_to_html;
 
 fn basic_image(show: bool, file_name: &str) {
     let w = Rgb::new(255, 255, 255);
@@ -102,17 +103,6 @@ fn trace_from_ndarray_rgba(show: bool, file_name: &str) {
     }
 }
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/maps/Cargo.toml b/examples/maps/Cargo.toml
@@ -6,6 +6,7 @@ edition = "2021"
 
 [dependencies]
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
 csv = "1.3"
 reqwest = { version = "0.11", features = ["blocking"] }
 
diff --git a/examples/maps/src/main.rs b/examples/maps/src/main.rs
@@ -1,5 +1,6 @@
 #![allow(dead_code)]
 
+use plotly_utils::write_example_to_html;
 use plotly::{
     color::Rgb,
     common::{Line, Marker, Mode},
@@ -159,17 +160,6 @@ fn density_mapbox(show: bool, file_name: &str) {
     }
 }
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/ndarray/src/main.rs b/examples/ndarray/src/main.rs
@@ -2,6 +2,7 @@
 
 use ndarray::{Array, Ix1, Ix2};
 use plotly::common::Mode;
+use plotly_utils::write_example_to_html;
 use plotly::ndarray::ArrayTraces;
 use plotly::{Plot, Scatter};
 
@@ -73,17 +74,6 @@ fn multiple_ndarray_traces_over_rows(show: bool, file_name: &str) {
     }
 }
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/plotly_utils/Cargo.toml b/examples/plotly_utils/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+name = "plotly_utils"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+plotly = { path = "../../plotly" } 
diff --git a/examples/plotly_utils/src/lib.rs b/examples/plotly_utils/src/lib.rs
@@ -0,0 +1,27 @@
+use plotly::Plot;
+
+/// Write a plot to HTML files for documentation and display
+/// 
+/// This function creates both an inline HTML file (for mdbook inclusion) and
+/// a standalone HTML file (for direct viewing). The inline file is prefixed
+/// with "inline_" and both files are placed in the "./output" directory.
+/// 
+/// # Arguments
+/// 
+/// * `plot` - The plot to write to HTML
+/// * `name` - The base name for the HTML files (without extension)
+/// 
+/// # Returns
+/// 
+/// The path to the standalone HTML file
+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);
+    std::fs::write(path, html).unwrap();
+    // Write standalone HTML
+    let path = format!("./output/{}.html", name);
+    plot.write_html(&path);
+    path
+} 
diff --git a/examples/scientific_charts/Cargo.toml b/examples/scientific_charts/Cargo.toml
@@ -6,3 +6,4 @@ edition = "2021"
 
 [dependencies]
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
diff --git a/examples/scientific_charts/src/main.rs b/examples/scientific_charts/src/main.rs
@@ -3,6 +3,7 @@
 use std::f64::consts::PI;
 
 use plotly::common::{ColorScale, ColorScalePalette, Font};
+use plotly_utils::write_example_to_html;
 use plotly::contour::Contours;
 use plotly::{Contour, HeatMap, Layout, Plot};
 
@@ -176,17 +177,6 @@ fn customized_heat_map(show: bool, file_name: &str) {
 }
 // ANCHOR_END: customized_heat_map
 
-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);
-    std::fs::write(path, html).unwrap();
-    // Write standalone HTML
-    let path = format!("./output/{}.html", name);
-    plot.write_html(&path);
-    path
-}
 
 fn main() {
     // Change false to true on any of these lines to display the example.
diff --git a/examples/shapes/Cargo.toml b/examples/shapes/Cargo.toml
@@ -7,5 +7,6 @@ edition = "2021"
 [dependencies]
 ndarray = "0.16"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }
 rand = "0.9"
 rand_distr = "0.5"
diff --git a/examples/shapes/src/main.rs b/examples/shapes/src/main.rs
diff --git a/examples/statistical_charts/Cargo.toml b/examples/statistical_charts/Cargo.toml
diff --git a/examples/statistical_charts/src/main.rs b/examples/statistical_charts/src/main.rs
diff --git a/examples/subplots/Cargo.toml b/examples/subplots/Cargo.toml
diff --git a/examples/subplots/src/main.rs b/examples/subplots/src/main.rs
diff --git a/examples/themes/Cargo.toml b/examples/themes/Cargo.toml
diff --git a/examples/themes/src/main.rs b/examples/themes/src/main.rs
diff --git a/plotly/src/layout/themes.rs b/plotly/src/layout/themes.rs
