feat: enhance timeline and waterfall plots with additional documentation and features (#64)

Author: mvanwyk

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "MD033": { "allowed_elements": ["div"] },
+  "MD013": { "line_length": 120 }
+}

docs/analysis_modules.md

@@ -11,7 +11,7 @@ social:
 
 <div class="clear" markdown>
 
-![Image title](../assets/images/analysis_modules/waterfall.svg){ align=right loading=lazy width="50%"}
+![Image title](assets/images/analysis_modules/waterfall.svg){ align=right loading=lazy width="50%"}
 
 Waterfall plots are particularly good for showing how different things add or subtract from a starting number. For
 instance,
@@ -42,3 +42,53 @@ waterfall_plot(
     rot=0,
 )
 ```
+
+### Timeline Plot
+
+<div class="clear" markdown>
+
+![Image title](assets/images/analysis_modules/time_plot.svg){ align=right loading=lazy width="50%"}
+
+Timeline plots are a fundamental tool for interpreting transactional data within a temporal context. By presenting data
+in a chronological sequence, these visualizations reveal patterns and trends that might otherwise remain hidden in raw
+numbers, making them essential for both historical analysis and forward-looking insights. They are particularly useful
+for:
+
+- Tracking sales performance across different periods (e.g., daily, weekly, monthly)
+- Identifying seasonal patterns or promotional impacts on sales
+- Comparing the performance of different product categories or store locations over time
+- Visualizing customer behavior trends, such as purchase frequency or average transaction value
+
+</div>
+
+Example:
+
+```python
+import numpy as np
+import pandas as pd
+
+from pyretailscience.standard_graphs import time_plot
+
+# Create a sample DataFrame with 3 groups
+rng = np.random.default_rng(42)
+df = pd.DataFrame(
+    {
+        "transaction_datetime": pd.concat([pd.Series(pd.date_range(start="2022-01-01", periods=200, freq="D"))] * 3),
+        "total_price": np.concatenate([rng.integers(1, 1000, size=200) * multiplier for multiplier in range(1, 4)]),
+        "group": ["Group A"] * 200 + ["Group B"] * 200 + ["Group C"] * 200,
+    },
+)
+
+time_plot(
+    df,
+    period="M",
+    group_col="group",
+    value_col="total_price",
+    agg_func="sum",
+    title="Monthly Sales by Customer Group",
+    y_label="Sales",
+    legend_title="Customer Group",
+    source_text="Source: PyRetailScience - Sales FY2024",
+    move_legend_outside=True,
+)
+```