refactor examples and add themes example to mdbook

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

Author: andrei-ng

.github/workflows/ci.yml

@@ -95,6 +95,7 @@ jobs:
           3d_charts,
           basic_charts,
           custom_controls,
+          customization,
           financial_charts,
           images,
           kaleido,
@@ -103,6 +104,7 @@ jobs:
           scientific_charts,
           shapes,
           subplots,
+          themes,
         ]
     runs-on: ubuntu-latest
     steps:
@@ -140,5 +142,6 @@ jobs:
           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
       - name: Build book 
         run: mdbook build docs/book

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)

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.

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" }

examples/3d_charts/src/main.rs

@@ -7,6 +7,7 @@ use plotly::{
     layout::{Axis, Camera, Layout, LayoutScene, Legend, Margin, ProjectionType},
     Mesh3D, Plot, Scatter3D, Surface,
 };
+use plotly_utils::write_example_to_html;
 use rand::Rng;
 
 // 3D Scatter Plots
@@ -259,18 +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.
     // Scatter3D Plots

examples/Cargo.toml

@@ -1,4 +1,4 @@
 [workspace]
-members = ["*"]
+members = ["*", "plotly_utils"]
 resolver = "2"
 exclude = ["jupyter", "target", "wasm-yew"]

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"

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.
 

examples/custom_controls/Cargo.toml

@@ -7,3 +7,4 @@ edition = "2021"
 [dependencies]
 itertools = "0.10"
 plotly = { path = "../../plotly" }
+plotly_utils = { path = "../plotly_utils" }

examples/custom_controls/src/main.rs

@@ -9,6 +9,7 @@ use plotly::{
     },
     Bar, HeatMap, Layout, Plot,
 };
+use plotly_utils::write_example_to_html;
 
 /// Display a bar chart with an associated dropdown selector to show different
 /// data.
@@ -117,18 +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.
 

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" }

examples/customization/src/main.rs

@@ -11,6 +11,7 @@ use plotly::{
     layout::{Center, DragMode, Mapbox, MapboxStyle, Margin},
     Configuration, DensityMapbox, Layout, Plot, Scatter, Scatter3D,
 };
+use plotly_utils::write_example_to_html;
 const DEFAULT_HTML_APP_NOT_FOUND: &str = "Could not find default application for HTML files.";
 
 fn density_mapbox_responsive_autofill(show: bool, file_name: &str) {
@@ -130,18 +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
     // open the generated file in the `output` folder.

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"

examples/financial_charts/src/main.rs

@@ -6,6 +6,7 @@ use std::path::PathBuf;
 use plotly::common::TickFormatStop;
 use plotly::layout::{Axis, RangeSelector, RangeSlider, SelectorButton, SelectorStep, StepMode};
 use plotly::{Candlestick, Layout, Ohlc, Plot, Scatter};
+use plotly_utils::write_example_to_html;
 use serde::Deserialize;
 
 #[derive(Deserialize)]
@@ -319,18 +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.
 

examples/images/Cargo.toml

@@ -11,3 +11,5 @@ plotly = { path = "../../plotly", features = [
     "plotly_image",
     "plotly_ndarray",
 ] }
+
+plotly_utils = { path = "../plotly_utils" }

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,18 +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.
     basic_image(false, "basic_image");

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"] }
 

examples/maps/src/main.rs

@@ -8,6 +8,7 @@ use plotly::{
     },
     DensityMapbox, Layout, Plot, ScatterGeo, ScatterMapbox,
 };
+use plotly_utils::write_example_to_html;
 
 fn scatter_mapbox(show: bool, file_name: &str) {
     let trace = ScatterMapbox::new(vec![45.5017], vec![-73.5673])
@@ -159,18 +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.
     scatter_mapbox(false, "scatter_mapbox");

examples/ndarray/Cargo.toml

@@ -7,3 +7,4 @@ edition = "2021"
 [dependencies]
 ndarray = "0.16"
 plotly = { path = "../../plotly", features = ["plotly_ndarray"] }
+plotly_utils = { path = "../plotly_utils" }

examples/ndarray/src/main.rs

@@ -4,6 +4,7 @@ use ndarray::{Array, Ix1, Ix2};
 use plotly::common::Mode;
 use plotly::ndarray::ArrayTraces;
 use plotly::{Plot, Scatter};
+use plotly_utils::write_example_to_html;
 
 fn single_ndarray_trace(show: bool, file_name: &str) {
     let n: usize = 11;
@@ -73,18 +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.
     single_ndarray_trace(false, "single_ndarray_trace");

examples/plotly_utils/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "plotly_utils"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+plotly = { path = "../../plotly" }