From fd78f50fa8d81f38cfadd06001d31e60c83406a0 Mon Sep 17 00:00:00 2001
From: "Jason M. Gates" <jmgate@sandia.gov>
Date: Mon, 24 Nov 2025 07:39:17 -0700
Subject: [PATCH] docs: Include output from first example in README

To better advertise what the package provides, without requiring the
reader to jump to (or further into) the documentation, include the
output from running the first example script with both stages defined in
the `README.md` file, which will be displayed on GitHub and PyPI, and
the `index.rst` file, which will be displayed on ReadTheDocs.

Note that this incurs a minimal maintenance burden, in that we'll need
to keep this output up-to-date with any changes to the package that
affect the output.
---
 README.md            | 51 +++++++++++++++++++++++++++++++++++++++++++
 doc/source/index.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)

diff --git a/README.md b/README.md
index 0cd5654..1dd0508 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,57 @@ if __name__ == "__main__":
     my_script.main(sys.argv[1:])
 ```
 
+Executing the script then yields
+```
+>>> my_staged_script.py --stage hello goodbye
+[07:34:19] ╭─────────────────────────────────────────────╮ staged_script.py:937
+           │ Greeting the user                           │
+           ╰─────────────────────────────────────────────╯
+           Executing:  echo 'Hello World'                  staged_script.py:827
+Hello World
+           `hello` stage duration:  0:00:00.020772         staged_script.py:476
+           ╭─────────────────────────────────────────────╮ staged_script.py:937
+           │ Bidding farewell                            │
+           ╰─────────────────────────────────────────────╯
+           Executing:  echo 'Goodbye World'                staged_script.py:827
+Goodbye World
+           `goodbye` stage duration:  0:00:00.012504       staged_script.py:476
+───────────────── ex_0_the_basics.py Script Execution Summary ─────────────────
+                                                           staged_script.py:920
+           ➤ Ran the following:
+
+               ex_0_the_basics.py \
+                   --stage hello goodbye \
+                   --hello-retry-attempts 0 \
+                   --hello-retry-delay 0 \
+                   --hello-retry-timeout 60 \
+                   --goodbye-retry-attempts 0 \
+                   --goodbye-retry-delay 0 \
+                   --goodbye-retry-timeout 60
+
+           ➤ Commands executed:
+
+               echo 'Hello World'
+               echo 'Goodbye World'
+
+           ➤ Timing results:
+
+               ┏━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+               ┃ Stage   ┃ Duration       ┃
+               ┡━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+               │ hello   │ 0:00:00.020772 │
+               │ goodbye │ 0:00:00.012504 │
+               ├─────────┼────────────────┤
+               │ Total   │ 0:00:00.035295 │
+               └─────────┴────────────────┘
+
+           ➤ Script result:
+
+               Success
+
+─────────────── End ex_0_the_basics.py Script Execution Summary ───────────────
+```
+
 For more detailed usage and API information, please see
 [our documentation][docs].
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9e354d3..b362e0e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -102,6 +102,58 @@ Once the package is installed, you can simply
    :lines: 10-
    :caption: ``example/ex_0_the_basics.py``
 
+Executing the script then yields
+
+.. code-block:: text
+
+   >>> ./ex_0_the_basics.py --stage hello goodbye
+   [07:34:19] ╭─────────────────────────────────────────────╮ staged_script.py:937
+              │ Greeting the user                           │
+              ╰─────────────────────────────────────────────╯
+              Executing:  echo 'Hello World'                  staged_script.py:827
+   Hello World
+              `hello` stage duration:  0:00:00.020772         staged_script.py:476
+              ╭─────────────────────────────────────────────╮ staged_script.py:937
+              │ Bidding farewell                            │
+              ╰─────────────────────────────────────────────╯
+              Executing:  echo 'Goodbye World'                staged_script.py:827
+   Goodbye World
+              `goodbye` stage duration:  0:00:00.012504       staged_script.py:476
+   ───────────────── ex_0_the_basics.py Script Execution Summary ─────────────────
+                                                              staged_script.py:920
+              ➤ Ran the following:
+
+                  ex_0_the_basics.py \
+                      --stage hello goodbye \
+                      --hello-retry-attempts 0 \
+                      --hello-retry-delay 0 \
+                      --hello-retry-timeout 60 \
+                      --goodbye-retry-attempts 0 \
+                      --goodbye-retry-delay 0 \
+                      --goodbye-retry-timeout 60
+
+              ➤ Commands executed:
+
+                  echo 'Hello World'
+                  echo 'Goodbye World'
+
+              ➤ Timing results:
+
+                  ┏━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+                  ┃ Stage   ┃ Duration       ┃
+                  ┡━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
+                  │ hello   │ 0:00:00.020772 │
+                  │ goodbye │ 0:00:00.012504 │
+                  ├─────────┼────────────────┤
+                  │ Total   │ 0:00:00.035295 │
+                  └─────────┴────────────────┘
+
+              ➤ Script result:
+
+                  Success
+
+   ─────────────── End ex_0_the_basics.py Script Execution Summary ───────────────
+
 For more detailed usage information, see the :doc:`examples` page.  For
 implementation details, see the :doc:`reference` documentation.