From df3107e1d45229f9a55e504cbf050291b15fadda Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 18:21:53 +0000
Subject: [PATCH] Add screenshots to documentation (#832)

Create include_screenshot macro
---
 masonry/examples/calc_masonry.rs              |   2 +-
 masonry/examples/custom_widget.rs             |   2 +-
 masonry/examples/grid_masonry.rs              |   2 +-
 masonry/examples/readme.md                    |  45 ++++++++++++++++--
 ...lc_masonry__tests__initial_screenshot.png} | Bin
 ...tom_widget__tests__initial_screenshot.png} | Bin
 ...id_masonry__tests__initial_screenshot.png} | Bin
 ...mple_image__tests__initial_screenshot.png} | Bin
 ...to_do_list__tests__initial_screenshot.png} | Bin
 masonry/examples/simple_image.rs              |   2 +-
 masonry/examples/to_do_list.rs                |   2 +-
 masonry/src/lib.rs                            |   2 +
 masonry/src/testing/screenshots.rs            |  27 +++++++++++
 masonry/src/widget/align.rs                   |   2 +
 masonry/src/widget/button.rs                  |   2 +
 masonry/src/widget/checkbox.rs                |   2 +
 masonry/src/widget/flex.rs                    |   2 +
 masonry/src/widget/grid.rs                    |   3 ++
 masonry/src/widget/label.rs                   |   2 +
 masonry/src/widget/progress_bar.rs            |   2 +
 masonry/src/widget/prose.rs                   |   2 +
 masonry/src/widget/scroll_bar.rs              |   3 ++
 masonry/src/widget/sized_box.rs               |   2 +
 masonry/src/widget/spinner.rs                 |   2 +
 masonry/src/widget/split.rs                   |   2 +
 masonry/src/widget/zstack.rs                  |   2 +
 26 files changed, 103 insertions(+), 9 deletions(-)
 rename masonry/examples/screenshots/{calc_masonry__tests__calc.png => calc_masonry__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{custom_widget__tests__custom_widget.png => custom_widget__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{grid_masonry__tests__grid_masonry.png => grid_masonry__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{simple_image__tests__grid_masonry.png => simple_image__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{to_do_list__tests__to_do_list.png => to_do_list__tests__initial_screenshot.png} (100%)

diff --git a/masonry/examples/calc_masonry.rs b/masonry/examples/calc_masonry.rs
index 1595268b..5c1c16be 100644
--- a/masonry/examples/calc_masonry.rs
+++ b/masonry/examples/calc_masonry.rs
@@ -414,7 +414,7 @@ mod tests {
     fn screenshot_test() {
         let mut harness = TestHarness::create(build_calc());
         assert_debug_snapshot!(harness.root_widget());
-        assert_render_snapshot!(harness, "calc");
+        assert_render_snapshot!(harness, "initial_screenshot");
 
         // TODO - Test clicking buttons
     }
diff --git a/masonry/examples/custom_widget.rs b/masonry/examples/custom_widget.rs
index 5d30c8fe..3da5e353 100644
--- a/masonry/examples/custom_widget.rs
+++ b/masonry/examples/custom_widget.rs
@@ -193,6 +193,6 @@ mod tests {
 
         let mut harness = TestHarness::create(CustomWidget(my_string));
         assert_debug_snapshot!(harness.root_widget());
-        assert_render_snapshot!(harness, "custom_widget");
+        assert_render_snapshot!(harness, "initial_screenshot");
     }
 }
diff --git a/masonry/examples/grid_masonry.rs b/masonry/examples/grid_masonry.rs
index 60e441c5..3dec8d3b 100644
--- a/masonry/examples/grid_masonry.rs
+++ b/masonry/examples/grid_masonry.rs
@@ -140,7 +140,7 @@ mod tests {
     fn screenshot_test() {
         let mut harness = TestHarness::create(make_grid(1.0));
         assert_debug_snapshot!(harness.root_widget());
-        assert_render_snapshot!(harness, "grid_masonry");
+        assert_render_snapshot!(harness, "initial_screenshot");
 
         // TODO - Test clicking buttons
     }
diff --git a/masonry/examples/readme.md b/masonry/examples/readme.md
index 46cb089e..b52a6fa6 100644
--- a/masonry/examples/readme.md
+++ b/masonry/examples/readme.md
@@ -1,7 +1,44 @@
 # Masonry examples
 
-TODO:
+## `hello_masonry`
 
-- List examples in this folder
-- Add screenshot test to each example
-- Use the screenshot in this list
+Simples possible Masonry app.
+
+## `two_textboxes`
+
+Example used to test text input and text focus.
+
+
+## `calc_masonry`
+
+![](screenshots/calc_masonry__tests__initial_screenshot.png)
+
+Calculator app.
+
+
+## `to_do_list`
+
+![](screenshots/to_do_list__tests__initial_screenshot.png)
+
+To-do list app.
+
+
+## `custom_widget`
+
+![](screenshots/custom_widget__tests__initial_screenshot.png)
+
+Static render showing off Vello's capabilities.
+
+
+## `grid_masonry`
+
+![](screenshots/grid_masonry__tests__initial_screenshot.png)
+
+Demonstration of the grid layout.
+
+
+## `simple_image`
+
+![](screenshots/simple_image__tests__initial_screenshot.png)
+
+Simple image example.
diff --git a/masonry/examples/screenshots/calc_masonry__tests__calc.png b/masonry/examples/screenshots/calc_masonry__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/calc_masonry__tests__calc.png
rename to masonry/examples/screenshots/calc_masonry__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/custom_widget__tests__custom_widget.png b/masonry/examples/screenshots/custom_widget__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/custom_widget__tests__custom_widget.png
rename to masonry/examples/screenshots/custom_widget__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/grid_masonry__tests__grid_masonry.png b/masonry/examples/screenshots/grid_masonry__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/grid_masonry__tests__grid_masonry.png
rename to masonry/examples/screenshots/grid_masonry__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/simple_image__tests__grid_masonry.png b/masonry/examples/screenshots/simple_image__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/simple_image__tests__grid_masonry.png
rename to masonry/examples/screenshots/simple_image__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/to_do_list__tests__to_do_list.png b/masonry/examples/screenshots/to_do_list__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/to_do_list__tests__to_do_list.png
rename to masonry/examples/screenshots/to_do_list__tests__initial_screenshot.png
diff --git a/masonry/examples/simple_image.rs b/masonry/examples/simple_image.rs
index 35218374..f594ecfd 100644
--- a/masonry/examples/simple_image.rs
+++ b/masonry/examples/simple_image.rs
@@ -63,6 +63,6 @@ mod tests {
     fn screenshot_test() {
         let mut harness = TestHarness::create(make_image());
         assert_debug_snapshot!(harness.root_widget());
-        assert_render_snapshot!(harness, "grid_masonry");
+        assert_render_snapshot!(harness, "initial_screenshot");
     }
 }
diff --git a/masonry/examples/to_do_list.rs b/masonry/examples/to_do_list.rs
index c5f641ea..c6d62d8e 100644
--- a/masonry/examples/to_do_list.rs
+++ b/masonry/examples/to_do_list.rs
@@ -88,7 +88,7 @@ mod tests {
     fn screenshot_test() {
         let mut harness = TestHarness::create(make_widget_tree());
         assert_debug_snapshot!(harness.root_widget());
-        assert_render_snapshot!(harness, "to_do_list");
+        assert_render_snapshot!(harness, "initial_screenshot");
 
         // TODO - Test clicking buttons
         // TODO - Test typing text
diff --git a/masonry/src/lib.rs b/masonry/src/lib.rs
index 4769e890..6a3c5b40 100644
--- a/masonry/src/lib.rs
+++ b/masonry/src/lib.rs
@@ -96,6 +96,8 @@
 //! [Druid]: https://crates.io/crates/druid
 //! [Xilem]: https://crates.io/crates/xilem
 //! [tracing_tracy]: https://crates.io/crates/tracing-tracy
+// TODO: Add screenshot. This can't use include_screenshot as that doesn't work with cargo-rdme
+// See https://github.com/linebender/xilem/issues/851
 
 // LINEBENDER LINT SET - lib.rs - v1
 // See https://linebender.org/wiki/canonical-lints/
diff --git a/masonry/src/testing/screenshots.rs b/masonry/src/testing/screenshots.rs
index 7d27efe6..57e808b1 100644
--- a/masonry/src/testing/screenshots.rs
+++ b/masonry/src/testing/screenshots.rs
@@ -6,6 +6,33 @@
 use image::{GenericImageView as _, RgbImage};
 use nv_flip::{FlipImageRgb8, DEFAULT_PIXELS_PER_DEGREE};
 
+#[cfg(docsrs)]
+#[doc(hidden)]
+#[macro_export]
+macro_rules! include_screenshot {
+    ($path:literal $(, $caption:literal)? $(,)?) => {
+        concat!(
+            "![", $($caption,)? "]",
+            "(", "https://media.githubusercontent.com/media/linebender/xilem/",
+            "masonry-v", env!("CARGO_PKG_VERSION"), "/masonry/src/", $path,
+            ")",
+        )
+    };
+}
+
+#[cfg(not(docsrs))]
+#[doc(hidden)]
+#[macro_export]
+/// Macro used to create markdown img tag, with a different URL when uploading to docs.rs.
+macro_rules! include_screenshot {
+    ($path:literal $(, $caption:literal)? $(,)?) => {
+        concat!(
+            "![", $($caption,)? "]",
+            "(", env!("CARGO_MANIFEST_DIR"), "/src/", $path, ")",
+        )
+    };
+}
+
 pub(crate) fn get_image_diff(ref_image: &RgbImage, new_image: &RgbImage) -> Option<RgbImage> {
     assert_eq!(
         (ref_image.width(), ref_image.height()),
diff --git a/masonry/src/widget/align.rs b/masonry/src/widget/align.rs
index f6d7ec43..4da55f39 100644
--- a/masonry/src/widget/align.rs
+++ b/masonry/src/widget/align.rs
@@ -24,6 +24,8 @@ use crate::{
 // TODO - Have child widget type as generic argument
 
 /// A widget that aligns its child.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__align__tests__right.png", "Right-aligned label.")]
 pub struct Align {
     align: UnitPoint,
     child: WidgetPod<dyn Widget>,
diff --git a/masonry/src/widget/button.rs b/masonry/src/widget/button.rs
index 4d9a532e..367dea5b 100644
--- a/masonry/src/widget/button.rs
+++ b/masonry/src/widget/button.rs
@@ -26,6 +26,8 @@ const LABEL_INSETS: Insets = Insets::uniform_xy(8., 2.);
 /// A button with a text label.
 ///
 /// Emits [`Action::ButtonPressed`] when pressed.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__button__tests__hello.png", "Button with text label.")]
 pub struct Button {
     label: WidgetPod<Label>,
 }
diff --git a/masonry/src/widget/checkbox.rs b/masonry/src/widget/checkbox.rs
index 70cd4ac1..54c16b60 100644
--- a/masonry/src/widget/checkbox.rs
+++ b/masonry/src/widget/checkbox.rs
@@ -19,6 +19,8 @@ use crate::{
 };
 
 /// A checkbox that can be toggled.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__checkbox__tests__hello_checked.png", "Checkbox with checked state.")]
 pub struct Checkbox {
     checked: bool,
     label: WidgetPod<Label>,
diff --git a/masonry/src/widget/flex.rs b/masonry/src/widget/flex.rs
index 71d42589..9b669fe6 100644
--- a/masonry/src/widget/flex.rs
+++ b/masonry/src/widget/flex.rs
@@ -19,6 +19,8 @@ use crate::{
 /// A container with either horizontal or vertical layout.
 ///
 /// This widget is the foundation of most layouts, and is highly configurable.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__flex__tests__col_main_axis_spaceAround.png", "Flex column with multiple labels.")]
 pub struct Flex {
     direction: Axis,
     cross_alignment: CrossAxisAlignment,
diff --git a/masonry/src/widget/grid.rs b/masonry/src/widget/grid.rs
index 621abf5c..19ba08b5 100644
--- a/masonry/src/widget/grid.rs
+++ b/masonry/src/widget/grid.rs
@@ -13,6 +13,9 @@ use crate::{
     QueryCtx, Size, TextEvent, Widget, WidgetId, WidgetPod,
 };
 
+/// A widget that arranges its children in a grid.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__grid__tests__with_changed_spacing.png", "Grid with buttons of various sizes.")]
 pub struct Grid {
     children: Vec<Child>,
     grid_width: i32,
diff --git a/masonry/src/widget/label.rs b/masonry/src/widget/label.rs
index 41df9000..c364af10 100644
--- a/masonry/src/widget/label.rs
+++ b/masonry/src/widget/label.rs
@@ -42,6 +42,8 @@ pub enum LineBreaking {
 ///
 /// This is useful for creating interactive widgets which internally
 /// need support for displaying text, such as a button.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__label__tests__styled_label.png", "Styled label.")]
 pub struct Label {
     text_layout: Layout<BrushIndex>,
     accessibility: LayoutAccessibility,
diff --git a/masonry/src/widget/progress_bar.rs b/masonry/src/widget/progress_bar.rs
index 3cc1a4f9..2dc970db 100644
--- a/masonry/src/widget/progress_bar.rs
+++ b/masonry/src/widget/progress_bar.rs
@@ -18,6 +18,8 @@ use crate::{
 };
 
 /// A progress bar.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__progress_bar__tests__25_percent_progressbar.png", "25% progress bar.")]
 pub struct ProgressBar {
     /// A value in the range `[0, 1]` inclusive, where 0 is 0% and 1 is 100% complete.
     ///
diff --git a/masonry/src/widget/prose.rs b/masonry/src/widget/prose.rs
index 212fd255..055e890e 100644
--- a/masonry/src/widget/prose.rs
+++ b/masonry/src/widget/prose.rs
@@ -36,6 +36,8 @@ const PROSE_PADDING: Padding = Padding::horizontal(2.0);
 /// as it enables users to copy/paste from the text.
 ///
 /// This widget has no actions.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__prose__tests__prose_alignment_flex.png", "Multiple lines with different alignments.")]
 pub struct Prose {
     text: WidgetPod<TextArea<false>>,
 
diff --git a/masonry/src/widget/scroll_bar.rs b/masonry/src/widget/scroll_bar.rs
index cfd1c64b..3b122c02 100644
--- a/masonry/src/widget/scroll_bar.rs
+++ b/masonry/src/widget/scroll_bar.rs
@@ -24,6 +24,9 @@ use crate::{
 // - Document names
 // - Document invariants
 
+/// A scrollbar.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__scroll_bar__tests__scrollbar_default.png", "Vertical scrollbar.")]
 pub struct ScrollBar {
     axis: Axis,
     pub(crate) cursor_progress: f64,
diff --git a/masonry/src/widget/sized_box.rs b/masonry/src/widget/sized_box.rs
index 658d7fd0..26858fdd 100644
--- a/masonry/src/widget/sized_box.rs
+++ b/masonry/src/widget/sized_box.rs
@@ -56,6 +56,8 @@ pub struct Padding {
 /// If not given a child, `SizedBox` will try to size itself as close to the specified height
 /// and width as possible given the parent's constraints. If height or width is not set,
 /// it will be treated as zero.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__sized_box__tests__label_box_with_outer_padding.png", "Box with blue border, pink background and a child label.")]
 pub struct SizedBox {
     child: Option<WidgetPod<dyn Widget>>,
     width: Option<f64>,
diff --git a/masonry/src/widget/spinner.rs b/masonry/src/widget/spinner.rs
index 2be598eb..787affb3 100644
--- a/masonry/src/widget/spinner.rs
+++ b/masonry/src/widget/spinner.rs
@@ -24,6 +24,8 @@ use crate::{
 /// that has a fixed width and height.
 ///
 /// [`SizedBox`]: crate::widget::SizedBox
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__spinner__tests__spinner_init.png", "Spinner frame.")]
 pub struct Spinner {
     t: f64,
     color: Color,
diff --git a/masonry/src/widget/split.rs b/masonry/src/widget/split.rs
index f96b7cf2..c265f465 100644
--- a/masonry/src/widget/split.rs
+++ b/masonry/src/widget/split.rs
@@ -21,6 +21,8 @@ use crate::{
 // TODO - Have child widget type as generic argument
 
 /// A container containing two other widgets, splitting the area either horizontally or vertically.
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__split__tests__columns.png", "Split panel with two labels.")]
 pub struct Split {
     split_axis: Axis,
     split_point_chosen: f64,
diff --git a/masonry/src/widget/zstack.rs b/masonry/src/widget/zstack.rs
index 4a6a625d..eed6ce6f 100644
--- a/masonry/src/widget/zstack.rs
+++ b/masonry/src/widget/zstack.rs
@@ -32,6 +32,8 @@ pub enum ChildAlignment {
 ///
 /// The alignment of how the children are placed can be specified globally using [`with_alignment`][Self::with_alignment].
 /// Each child can additionally override the global alignment using [`ChildAlignment::SelfAligned`].
+///
+#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__zstack__tests__zstack_alignment_default.png", "Red foreground widget on top of blue background widget.")]
 #[derive(Default)]
 pub struct ZStack {
     children: Vec<Child>,