From 5c4c6ad8a433341d323ae24aad167380017d65ff Mon Sep 17 00:00:00 2001
From: Richard Wesley <hawkfish@electricfish.com>
Date: Tue, 7 Sep 2021 13:11:18 -0700
Subject: [PATCH] Add examples for Fold and Unfold.

---
 docs/transforms/reshapes/fold.rst   | 52 +++++++++++++++++++++++++++--
 docs/transforms/reshapes/unfold.rst | 52 +++++++++++++++++++++++++++--
 2 files changed, 99 insertions(+), 5 deletions(-)

diff --git a/docs/transforms/reshapes/fold.rst b/docs/transforms/reshapes/fold.rst
index b0677cd..9fef315 100644
--- a/docs/transforms/reshapes/fold.rst
+++ b/docs/transforms/reshapes/fold.rst
@@ -43,5 +43,53 @@ Usage
 
 .. code-block:: python
 
-   Fold(p, ('Sales 1992', 'Sales 1993', 'Sales 1994',), ('Year', 'Sales',))
-   Fold(p, ('Sales 1992', 'Sales 1993', 'Sales 1994', 'Profit 1992', 'Profit 1993', 'Profit 1994',), ('Year', 'Sales', 'Profit',))
+   Fold(p, ('Sales 1992', 'Sales 1993', 'Sales 1994',),
+           ('Year', 'Sales',), ('1992', '1993', '1994',))
+   Fold(p, ('Sales 1992', 'Sales 1993', 'Sales 1994', 'Profit 1992', 'Profit 1993', 'Profit 1994',),
+           ('Year', 'Sales', 'Profit',), ('1992', '1993', '1994',))
+
+Examples
+^^^^^^^^
+
+Single Fold
+-----------
+
+.. csv-table:: Input
+    :header: "Key", "Sales 1992", "Sales 1993", "Sales 1994"
+    :align: left
+
+    0, "S-0-1992", "S-0-1993", "S-0-1994"
+    1, "S-1-1992", "S-1-1993", "S-1-1994"
+
+.. csv-table:: Output
+    :header: "Key", "Year", "Sales"
+    :align: left
+
+    0, 1992, "S-0-1992"
+    0, 1993, "S-0-1993"
+    0, 1994, "S-0-1994"
+    1, 1992, "S-1-1992"
+    1, 1993, "S-1-1993"
+    1, 1994, "S-1-1994"
+
+Multiple Folds
+--------------
+
+.. csv-table:: Input
+    :header: "Key", "Sales 1992", "Sales 1993", "Sales 1994", "Profit 1992", "Profit 1993", "Profit 1994"
+    :align: left
+    :widths: 1, 8, 8, 8, 8, 8, 8
+
+    0, "S-0-1992", "S-0-1993", "S-0-1994", "P-0-1992", "P-0-1993", "P-0-1994"
+    1, "S-1-1992", "S-1-1993", "S-1-1994", "P-1-1992", "P-1-1993", "P-1-1994"
+
+.. csv-table:: Output
+    :header: "Key", "Year", "Sales", "Profit"
+    :align: left
+
+    0, 1992, "S-0-1992", "P-0-1992"
+    0, 1993, "S-0-1993", "P-0-1993"
+    0, 1994, "S-0-1994", "P-0-1994"
+    1, 1992, "S-1-1992", "P-1-1992"
+    1, 1993, "S-1-1993", "P-1-1993"
+    1, 1994, "S-1-1994", "P-1-1994"
diff --git a/docs/transforms/reshapes/unfold.rst b/docs/transforms/reshapes/unfold.rst
index 7b7219e..158a4ff 100644
--- a/docs/transforms/reshapes/unfold.rst
+++ b/docs/transforms/reshapes/unfold.rst
@@ -6,9 +6,9 @@ Unfold: Rotate one field to many
 .. py:class:: Unfold(source, inputs, outputs)
 
     The ``Unfold`` transform unfolds (pivots) a set of fields.
-    Simple unfolding consists of rotating a single input fields into multiple output fields.
-    This can be generalised to multiple input fields where the output fields
-    are broken up into equal-sized groups, each of which is generated from one of the input fields.
+    Simple unfolding consists of rotating a single input field into multiple output fields.
+    This can be generalised to multiple input fields where the output fields are broken up into equal-sized groups,
+    and each group is generated from one of the input fields.
     ``Unfold`` is the inverse of :py:class:`Fold`.
 
     .. py:attribute:: source
@@ -45,3 +45,49 @@ Usage
 
    Unfold(p, ('Year', 'Sales',), ('Sales 1992', 'Sales 1993', 'Sales 1994',))
    Unfold(p, ('Year', 'Sales', 'Profit',), ('Sales 1992', 'Sales 1993', 'Sales 1994', 'Profit 1992', 'Profit 1993', 'Profit 1994',))
+
+Examples
+^^^^^^^^
+
+Single Fold
+-----------
+
+.. csv-table:: Input
+    :header: "Key", "Year", "Sales"
+    :align: left
+
+    0, 1992, "S-0-1992"
+    0, 1993, "S-0-1993"
+    0, 1994, "S-0-1994"
+    1, 1992, "S-1-1992"
+    1, 1993, "S-1-1993"
+    1, 1994, "S-1-1994"
+
+.. csv-table:: Output
+    :header: "Key", "Sales 1992", "Sales 1993", "Sales 1994"
+    :align: left
+
+    0, "S-0-1992", "S-0-1993", "S-0-1994"
+    1, "S-1-1992", "S-1-1993", "S-1-1994"
+
+Multiple Folds
+--------------
+
+.. csv-table:: Input
+    :header: "Key", "Year", "Sales", "Profit"
+    :align: left
+
+    0, 1992, "S-0-1992", "P-0-1992"
+    0, 1993, "S-0-1993", "P-0-1993"
+    0, 1994, "S-0-1994", "P-0-1994"
+    1, 1992, "S-1-1992", "P-1-1992"
+    1, 1993, "S-1-1993", "P-1-1993"
+    1, 1994, "S-1-1994", "P-1-1994"
+
+.. csv-table:: Output
+    :header: "Key", "Sales 1992", "Sales 1993", "Sales 1994", "Profit 1992", "Profit 1993", "Profit 1994"
+    :align: left
+    :widths: 1, 8, 8, 8, 8, 8, 8
+
+    0, "S-0-1992", "S-0-1993", "S-0-1994", "P-0-1992", "P-0-1993", "P-0-1994"
+    1, "S-1-1992", "S-1-1993", "S-1-1994", "P-1-1992", "P-1-1993", "P-1-1994"