From 300503ab74a7912a14da72cb9cdc481c5c046f00 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 16 Jan 2025 16:54:19 +0100
Subject: [PATCH 1/7] Add screenshots to documentation

Create include_screenshot macro
---
 masonry/src/testing/screenshots.rs | 36 ++++++++++++++++++++++++++++++
 masonry/src/widget/align.rs        |  3 +++
 2 files changed, 39 insertions(+)

diff --git a/masonry/src/testing/screenshots.rs b/masonry/src/testing/screenshots.rs
index 7d27efe6d..9a2479371 100644
--- a/masonry/src/testing/screenshots.rs
+++ b/masonry/src/testing/screenshots.rs
@@ -6,6 +6,42 @@
 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://raw.githubusercontent.com/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, ")",
+        )
+    };
+}
+
+// [!Image alt](link)
+
+// https://raw.githubusercontent.com/linebender/xilem/7f40266bd831c3f8e715bf7af325e3a53e046612/masonry/src/widget/screenshots/masonry__widget__align__tests__centered.png
+
+#[cfg(FALSE)]
+include_screenshot!("hello");
+
+#[cfg_attr(docsrs, doc = r" This is a doc comment.")]
+#[cfg_attr(not(docsrs), doc = r" This is a doc comment.")]
 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 f6d7ec437..419002202 100644
--- a/masonry/src/widget/align.rs
+++ b/masonry/src/widget/align.rs
@@ -14,6 +14,7 @@ use tracing::{trace_span, Span};
 use vello::Scene;
 
 use crate::contexts::AccessCtx;
+use crate::include_screenshot;
 use crate::paint_scene_helpers::UnitPoint;
 use crate::widget::WidgetPod;
 use crate::{
@@ -24,6 +25,8 @@ use crate::{
 // TODO - Have child widget type as generic argument
 
 /// A widget that aligns its child.
+///
+#[doc = include_screenshot!("widget/screenshots/masonry__widget__align__tests__right.png", "Right-aligned label")]
 pub struct Align {
     align: UnitPoint,
     child: WidgetPod<dyn Widget>,

From 2b45f6b087455048edee258904fe526c33dd893e Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 16:23:31 +0100
Subject: [PATCH 2/7] Add screenshots to all widgets

Remove cruft
---
 masonry/src/testing/screenshots.rs | 12 +++++-------
 masonry/src/widget/align.rs        |  3 +--
 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 ++
 14 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/masonry/src/testing/screenshots.rs b/masonry/src/testing/screenshots.rs
index 9a2479371..127b2be9e 100644
--- a/masonry/src/testing/screenshots.rs
+++ b/masonry/src/testing/screenshots.rs
@@ -20,6 +20,11 @@ macro_rules! include_screenshot {
     };
 }
 
+// TODO:
+// - Check whether the docs.rs trick actually works.
+// - Check whether this method will work with cargo rdme.
+// - Make better screenshots than the ones we currently use.
+
 #[cfg(not(docsrs))]
 #[doc(hidden)]
 #[macro_export]
@@ -33,13 +38,6 @@ macro_rules! include_screenshot {
     };
 }
 
-// [!Image alt](link)
-
-// https://raw.githubusercontent.com/linebender/xilem/7f40266bd831c3f8e715bf7af325e3a53e046612/masonry/src/widget/screenshots/masonry__widget__align__tests__centered.png
-
-#[cfg(FALSE)]
-include_screenshot!("hello");
-
 #[cfg_attr(docsrs, doc = r" This is a doc comment.")]
 #[cfg_attr(not(docsrs), doc = r" This is a doc comment.")]
 pub(crate) fn get_image_diff(ref_image: &RgbImage, new_image: &RgbImage) -> Option<RgbImage> {
diff --git a/masonry/src/widget/align.rs b/masonry/src/widget/align.rs
index 419002202..96d037b8a 100644
--- a/masonry/src/widget/align.rs
+++ b/masonry/src/widget/align.rs
@@ -14,7 +14,6 @@ use tracing::{trace_span, Span};
 use vello::Scene;
 
 use crate::contexts::AccessCtx;
-use crate::include_screenshot;
 use crate::paint_scene_helpers::UnitPoint;
 use crate::widget::WidgetPod;
 use crate::{
@@ -26,7 +25,7 @@ use crate::{
 
 /// A widget that aligns its child.
 ///
-#[doc = include_screenshot!("widget/screenshots/masonry__widget__align__tests__right.png", "Right-aligned label")]
+#[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 4d9a532e3..805cd772f 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 70cd4ac15..8ce8e25a6 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 71d425893..e983dfa72 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 621abf5c8..a60cedf85 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 41df90006..7a6e5794f 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 3cc1a4f93..703e68771 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 212fd2556..5d4c5988a 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 cfd1c64b9..86e287eca 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 658d7fd00..a634c4457 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 2be598ebe..be1b4ffba 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 f96b7cf27..bb9be018e 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 4a6a625dc..3aa7e76f9 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>,

From 24b0a44b77de8bbc9fe5401da3b12e75836deae5 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 16:34:59 +0100
Subject: [PATCH 3/7] Add screenshots to `masonry/examples/readme.md`

---
 masonry/examples/calc_masonry.rs              |   2 +-
 masonry/examples/custom_widget.rs             |   2 +-
 masonry/examples/grid_masonry.rs              |   2 +-
 masonry/examples/readme.md                    |  43 ++++++++++++++++--
 ... calc_masonry__tests__base_screenshot.png} | Bin
 ...custom_widget__tests__base_screenshot.png} | Bin
 ... grid_masonry__tests__base_screenshot.png} | Bin
 ... simple_image__tests__base_screenshot.png} | Bin
 ...=> to_do_list__tests__base_screenshot.png} | Bin
 masonry/examples/simple_image.rs              |   2 +-
 masonry/examples/to_do_list.rs                |   2 +-
 11 files changed, 44 insertions(+), 9 deletions(-)
 rename masonry/examples/screenshots/{calc_masonry__tests__calc.png => calc_masonry__tests__base_screenshot.png} (100%)
 rename masonry/examples/screenshots/{custom_widget__tests__custom_widget.png => custom_widget__tests__base_screenshot.png} (100%)
 rename masonry/examples/screenshots/{grid_masonry__tests__grid_masonry.png => grid_masonry__tests__base_screenshot.png} (100%)
 rename masonry/examples/screenshots/{simple_image__tests__grid_masonry.png => simple_image__tests__base_screenshot.png} (100%)
 rename masonry/examples/screenshots/{to_do_list__tests__to_do_list.png => to_do_list__tests__base_screenshot.png} (100%)

diff --git a/masonry/examples/calc_masonry.rs b/masonry/examples/calc_masonry.rs
index 1595268b7..c1b8955c2 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, "base_screenshot");
 
         // TODO - Test clicking buttons
     }
diff --git a/masonry/examples/custom_widget.rs b/masonry/examples/custom_widget.rs
index 5d30c8fe4..43b60b1b8 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, "base_screenshot");
     }
 }
diff --git a/masonry/examples/grid_masonry.rs b/masonry/examples/grid_masonry.rs
index 60e441c58..6542af0de 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, "base_screenshot");
 
         // TODO - Test clicking buttons
     }
diff --git a/masonry/examples/readme.md b/masonry/examples/readme.md
index 46cb089ee..dea811aa4 100644
--- a/masonry/examples/readme.md
+++ b/masonry/examples/readme.md
@@ -1,7 +1,42 @@
 # 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`
+
+![alt text](screenshots/calc_masonry__tests__base_screenshot.png)
+
+Calculator app.
+
+
+## `to_do_list`
+
+![alt text](screenshots/to_do_list__tests__base_screenshot.png)
+
+To-do list app.
+
+
+## `custom_widget`
+![alt text](screenshots/custom_widget__tests__base_screenshot.png)
+
+Static render showing off Vello's capabilities.
+
+
+## `grid_masonry`
+![alt text](screenshots/grid_masonry__tests__base_screenshot.png)
+
+Demonstration of the grid layout.
+
+
+## `simple_image`
+
+![alt text](screenshots/simple_image__tests__base_screenshot.png)
+
+Simple image example.
diff --git a/masonry/examples/screenshots/calc_masonry__tests__calc.png b/masonry/examples/screenshots/calc_masonry__tests__base_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/calc_masonry__tests__calc.png
rename to masonry/examples/screenshots/calc_masonry__tests__base_screenshot.png
diff --git a/masonry/examples/screenshots/custom_widget__tests__custom_widget.png b/masonry/examples/screenshots/custom_widget__tests__base_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/custom_widget__tests__custom_widget.png
rename to masonry/examples/screenshots/custom_widget__tests__base_screenshot.png
diff --git a/masonry/examples/screenshots/grid_masonry__tests__grid_masonry.png b/masonry/examples/screenshots/grid_masonry__tests__base_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/grid_masonry__tests__grid_masonry.png
rename to masonry/examples/screenshots/grid_masonry__tests__base_screenshot.png
diff --git a/masonry/examples/screenshots/simple_image__tests__grid_masonry.png b/masonry/examples/screenshots/simple_image__tests__base_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/simple_image__tests__grid_masonry.png
rename to masonry/examples/screenshots/simple_image__tests__base_screenshot.png
diff --git a/masonry/examples/screenshots/to_do_list__tests__to_do_list.png b/masonry/examples/screenshots/to_do_list__tests__base_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__base_screenshot.png
diff --git a/masonry/examples/simple_image.rs b/masonry/examples/simple_image.rs
index 35218374b..a8def6223 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, "base_screenshot");
     }
 }
diff --git a/masonry/examples/to_do_list.rs b/masonry/examples/to_do_list.rs
index c5f641ea0..a92370e45 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, "base_screenshot");
 
         // TODO - Test clicking buttons
         // TODO - Test typing text

From a1610961f5afa0f1d41a6d46b21f869ea0111458 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 17:55:12 +0100
Subject: [PATCH 4/7] Address code review

---
 masonry/examples/readme.md         | 12 +++++++-----
 masonry/src/testing/screenshots.rs |  4 +---
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/masonry/examples/readme.md b/masonry/examples/readme.md
index dea811aa4..aeb55a2f0 100644
--- a/masonry/examples/readme.md
+++ b/masonry/examples/readme.md
@@ -11,32 +11,34 @@ Example used to test text input and text focus.
 
 ## `calc_masonry`
 
-![alt text](screenshots/calc_masonry__tests__base_screenshot.png)
+![](screenshots/calc_masonry__tests__base_screenshot.png)
 
 Calculator app.
 
 
 ## `to_do_list`
 
-![alt text](screenshots/to_do_list__tests__base_screenshot.png)
+![](screenshots/to_do_list__tests__base_screenshot.png)
 
 To-do list app.
 
 
 ## `custom_widget`
-![alt text](screenshots/custom_widget__tests__base_screenshot.png)
+
+![](screenshots/custom_widget__tests__base_screenshot.png)
 
 Static render showing off Vello's capabilities.
 
 
 ## `grid_masonry`
-![alt text](screenshots/grid_masonry__tests__base_screenshot.png)
+
+![](screenshots/grid_masonry__tests__base_screenshot.png)
 
 Demonstration of the grid layout.
 
 
 ## `simple_image`
 
-![alt text](screenshots/simple_image__tests__base_screenshot.png)
+![](screenshots/simple_image__tests__base_screenshot.png)
 
 Simple image example.
diff --git a/masonry/src/testing/screenshots.rs b/masonry/src/testing/screenshots.rs
index 127b2be9e..36e73be77 100644
--- a/masonry/src/testing/screenshots.rs
+++ b/masonry/src/testing/screenshots.rs
@@ -13,7 +13,7 @@ macro_rules! include_screenshot {
     ($path:literal $(, $caption:literal)? $(,)?) => {
         concat!(
             "![", $($caption,)? "]",
-            "(", "https://raw.githubusercontent.com/linebender/xilem/",
+            "(", "https://media.githubusercontent.com/media/linebender/xilem/",
             "masonry-v", env!("CARGO_PKG_VERSION"), "/masonry/src/", $path,
             ")",
         )
@@ -38,8 +38,6 @@ macro_rules! include_screenshot {
     };
 }
 
-#[cfg_attr(docsrs, doc = r" This is a doc comment.")]
-#[cfg_attr(not(docsrs), doc = r" This is a doc comment.")]
 pub(crate) fn get_image_diff(ref_image: &RgbImage, new_image: &RgbImage) -> Option<RgbImage> {
     assert_eq!(
         (ref_image.width(), ref_image.height()),

From c516cb13380ee9d2127d34d9e6835f72226e3506 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 17:57:21 +0100
Subject: [PATCH 5/7] Add periods to alt texts.

---
 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         | 2 +-
 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   | 2 +-
 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 +-
 13 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/masonry/src/widget/align.rs b/masonry/src/widget/align.rs
index 96d037b8a..4da55f39e 100644
--- a/masonry/src/widget/align.rs
+++ b/masonry/src/widget/align.rs
@@ -25,7 +25,7 @@ use crate::{
 
 /// A widget that aligns its child.
 ///
-#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__align__tests__right.png", "Right-aligned label")]
+#[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 805cd772f..367dea5be 100644
--- a/masonry/src/widget/button.rs
+++ b/masonry/src/widget/button.rs
@@ -27,7 +27,7 @@ const LABEL_INSETS: Insets = Insets::uniform_xy(8., 2.);
 ///
 /// Emits [`Action::ButtonPressed`] when pressed.
 ///
-#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__button__tests__hello.png", "Button with text label")]
+#[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 8ce8e25a6..54c16b60b 100644
--- a/masonry/src/widget/checkbox.rs
+++ b/masonry/src/widget/checkbox.rs
@@ -20,7 +20,7 @@ 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")]
+#[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 e983dfa72..9b669fe64 100644
--- a/masonry/src/widget/flex.rs
+++ b/masonry/src/widget/flex.rs
@@ -20,7 +20,7 @@ use crate::{
 ///
 /// 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")]
+#[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 a60cedf85..19ba08b5b 100644
--- a/masonry/src/widget/grid.rs
+++ b/masonry/src/widget/grid.rs
@@ -15,7 +15,7 @@ use crate::{
 
 /// 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")]
+#[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 7a6e5794f..c364af10b 100644
--- a/masonry/src/widget/label.rs
+++ b/masonry/src/widget/label.rs
@@ -43,7 +43,7 @@ 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")]
+#[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 703e68771..2dc970dbb 100644
--- a/masonry/src/widget/progress_bar.rs
+++ b/masonry/src/widget/progress_bar.rs
@@ -19,7 +19,7 @@ use crate::{
 
 /// A progress bar.
 ///
-#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__progress_bar__tests__25_percent_progressbar.png", "25% 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 5d4c5988a..055e890eb 100644
--- a/masonry/src/widget/prose.rs
+++ b/masonry/src/widget/prose.rs
@@ -37,7 +37,7 @@ const PROSE_PADDING: Padding = Padding::horizontal(2.0);
 ///
 /// This widget has no actions.
 ///
-#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__prose__tests__prose_alignment_flex.png", "Multiple lines with different alignments")]
+#[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 86e287eca..3b122c02e 100644
--- a/masonry/src/widget/scroll_bar.rs
+++ b/masonry/src/widget/scroll_bar.rs
@@ -26,7 +26,7 @@ use crate::{
 
 /// A scrollbar.
 ///
-#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__scroll_bar__tests__scrollbar_default.png", "Vertical 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 a634c4457..26858fdd0 100644
--- a/masonry/src/widget/sized_box.rs
+++ b/masonry/src/widget/sized_box.rs
@@ -57,7 +57,7 @@ pub struct Padding {
 /// 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")]
+#[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 be1b4ffba..787affb32 100644
--- a/masonry/src/widget/spinner.rs
+++ b/masonry/src/widget/spinner.rs
@@ -25,7 +25,7 @@ use crate::{
 ///
 /// [`SizedBox`]: crate::widget::SizedBox
 ///
-#[doc = crate::include_screenshot!("widget/screenshots/masonry__widget__spinner__tests__spinner_init.png", "Spinner frame")]
+#[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 bb9be018e..c265f4650 100644
--- a/masonry/src/widget/split.rs
+++ b/masonry/src/widget/split.rs
@@ -22,7 +22,7 @@ use crate::{
 
 /// 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")]
+#[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 3aa7e76f9..eed6ce6f2 100644
--- a/masonry/src/widget/zstack.rs
+++ b/masonry/src/widget/zstack.rs
@@ -33,7 +33,7 @@ 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")]
+#[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>,

From f799e0d16b324b1ee89d95be477f900a019aa2c1 Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 18:00:58 +0100
Subject: [PATCH 6/7] Rename base screenshots to initial screenshots

---
 masonry/examples/calc_masonry.rs                    |   2 +-
 masonry/examples/custom_widget.rs                   |   2 +-
 masonry/examples/grid_masonry.rs                    |   2 +-
 masonry/examples/readme.md                          |  10 +++++-----
 ... => calc_masonry__tests__initial_screenshot.png} | Bin
 ...=> custom_widget__tests__initial_screenshot.png} | Bin
 ... => grid_masonry__tests__initial_screenshot.png} | Bin
 ... => simple_image__tests__initial_screenshot.png} | Bin
 ...ng => to_do_list__tests__initial_screenshot.png} | Bin
 masonry/examples/simple_image.rs                    |   2 +-
 masonry/examples/to_do_list.rs                      |   2 +-
 11 files changed, 10 insertions(+), 10 deletions(-)
 rename masonry/examples/screenshots/{calc_masonry__tests__base_screenshot.png => calc_masonry__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{custom_widget__tests__base_screenshot.png => custom_widget__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{grid_masonry__tests__base_screenshot.png => grid_masonry__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{simple_image__tests__base_screenshot.png => simple_image__tests__initial_screenshot.png} (100%)
 rename masonry/examples/screenshots/{to_do_list__tests__base_screenshot.png => to_do_list__tests__initial_screenshot.png} (100%)

diff --git a/masonry/examples/calc_masonry.rs b/masonry/examples/calc_masonry.rs
index c1b8955c2..5c1c16be7 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, "base_screenshot");
+        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 43b60b1b8..3da5e3537 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, "base_screenshot");
+        assert_render_snapshot!(harness, "initial_screenshot");
     }
 }
diff --git a/masonry/examples/grid_masonry.rs b/masonry/examples/grid_masonry.rs
index 6542af0de..3dec8d3b5 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, "base_screenshot");
+        assert_render_snapshot!(harness, "initial_screenshot");
 
         // TODO - Test clicking buttons
     }
diff --git a/masonry/examples/readme.md b/masonry/examples/readme.md
index aeb55a2f0..b52a6fa63 100644
--- a/masonry/examples/readme.md
+++ b/masonry/examples/readme.md
@@ -11,34 +11,34 @@ Example used to test text input and text focus.
 
 ## `calc_masonry`
 
-![](screenshots/calc_masonry__tests__base_screenshot.png)
+![](screenshots/calc_masonry__tests__initial_screenshot.png)
 
 Calculator app.
 
 
 ## `to_do_list`
 
-![](screenshots/to_do_list__tests__base_screenshot.png)
+![](screenshots/to_do_list__tests__initial_screenshot.png)
 
 To-do list app.
 
 
 ## `custom_widget`
 
-![](screenshots/custom_widget__tests__base_screenshot.png)
+![](screenshots/custom_widget__tests__initial_screenshot.png)
 
 Static render showing off Vello's capabilities.
 
 
 ## `grid_masonry`
 
-![](screenshots/grid_masonry__tests__base_screenshot.png)
+![](screenshots/grid_masonry__tests__initial_screenshot.png)
 
 Demonstration of the grid layout.
 
 
 ## `simple_image`
 
-![](screenshots/simple_image__tests__base_screenshot.png)
+![](screenshots/simple_image__tests__initial_screenshot.png)
 
 Simple image example.
diff --git a/masonry/examples/screenshots/calc_masonry__tests__base_screenshot.png b/masonry/examples/screenshots/calc_masonry__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/calc_masonry__tests__base_screenshot.png
rename to masonry/examples/screenshots/calc_masonry__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/custom_widget__tests__base_screenshot.png b/masonry/examples/screenshots/custom_widget__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/custom_widget__tests__base_screenshot.png
rename to masonry/examples/screenshots/custom_widget__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/grid_masonry__tests__base_screenshot.png b/masonry/examples/screenshots/grid_masonry__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/grid_masonry__tests__base_screenshot.png
rename to masonry/examples/screenshots/grid_masonry__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/simple_image__tests__base_screenshot.png b/masonry/examples/screenshots/simple_image__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/simple_image__tests__base_screenshot.png
rename to masonry/examples/screenshots/simple_image__tests__initial_screenshot.png
diff --git a/masonry/examples/screenshots/to_do_list__tests__base_screenshot.png b/masonry/examples/screenshots/to_do_list__tests__initial_screenshot.png
similarity index 100%
rename from masonry/examples/screenshots/to_do_list__tests__base_screenshot.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 a8def6223..f594ecfda 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, "base_screenshot");
+        assert_render_snapshot!(harness, "initial_screenshot");
     }
 }
diff --git a/masonry/examples/to_do_list.rs b/masonry/examples/to_do_list.rs
index a92370e45..c6d62d8ef 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, "base_screenshot");
+        assert_render_snapshot!(harness, "initial_screenshot");
 
         // TODO - Test clicking buttons
         // TODO - Test typing text

From 240e9c77f7fa1bd395f10bf72337556d86244e2c Mon Sep 17 00:00:00 2001
From: Olivier FAURE <couteaubleu@gmail.com>
Date: Thu, 23 Jan 2025 18:56:47 +0100
Subject: [PATCH 7/7] Add TODO comment about screenshots in lib.rs

---
 masonry/src/lib.rs                 | 2 ++
 masonry/src/testing/screenshots.rs | 5 -----
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/masonry/src/lib.rs b/masonry/src/lib.rs
index 4769e8901..6a3c5b408 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 36e73be77..57e808b1a 100644
--- a/masonry/src/testing/screenshots.rs
+++ b/masonry/src/testing/screenshots.rs
@@ -20,11 +20,6 @@ macro_rules! include_screenshot {
     };
 }
 
-// TODO:
-// - Check whether the docs.rs trick actually works.
-// - Check whether this method will work with cargo rdme.
-// - Make better screenshots than the ones we currently use.
-
 #[cfg(not(docsrs))]
 #[doc(hidden)]
 #[macro_export]