Add documentation examples for ScatterPlot, MultipleColumnChart and StackedBarChart

docs/user-guide/charts/multiple-column-charts.md

@@ -1,5 +1,86 @@
 # MultipleColumnChart
 
+This example, drawn from [Datawrapper's official documentation](https://www.datawrapper.de/charts/multiple-columns), demonstrates how to create small multiple column charts showing population growth in major cities from 1950 to 2035. The chart features custom panel titles with country information, highlighted data for 2025, a range annotation to mark the projection period and a 4-column grid layout.
+
+<iframe title="Population of the world's largest cities, 1950 to 2035" aria-label="Multiple Columns" id="datawrapper-chart-8kNfG" src="https://datawrapper.dwcdn.net/8kNfG/1/" scrolling="no" frameborder="0" style="width: 0; min-width: 100% !important; border: none;" height="460" data-external="1"></iframe><script type="text/javascript">window.addEventListener("message",function(a){if(void 0!==a.data["datawrapper-height"]){var e=document.querySelectorAll("iframe");for(var t in a.data["datawrapper-height"])for(var r,i=0;r=e[i];i++)if(r.contentWindow===a.source){var d=a.data["datawrapper-height"][t]+"px";r.style.height=d}}});</script>
+
+```python
+import pandas as pd
+import datawrapper as dw
+
+# Load population data from GitHub
+df = pd.read_csv(
+    "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/multiple_column/population.csv",
+    sep="\t"
+)
+
+chart = dw.MultipleColumnChart(
+    # Chart title
+    title="Population of the world's largest cities, 1950 to 2035",
+    # Data source attribution
+    source_name="Our World in Data",
+    source_url="https://ourworldindata.org/urbanization",
+    # Data from pandas DataFrame
+    data=df,
+    # Layout configuration - 4 columns on desktop, 2 on mobile
+    grid_layout="fixedCount",
+    grid_column=4,
+    grid_column_mobile=2,
+    grid_row_height=140,
+    # Sort panels by end value (2035 population) in descending order
+    sort=True,
+    sort_by="end",
+    sort_reverse=False,
+    # Set custom column color with highlighted year for 2025
+    base_color="#c9a291",
+    color_category={
+        "2025": "#c71e1d"
+    },
+    # Format y-axis with abbreviated numbers
+    y_grid_format=dw.NumberFormat.ABBREVIATED_ONE_DECIMAL,
+    y_grid_labels="inside",
+    y_grid_label_align="left",
+    # Custom panel titles with city and country information
+    panels=[
+        {"column": "Delhi", "title": "Delhi, <span style=\"color:gray; font-weight: normal;\">India</span>"},
+        {"column": "Dhaka", "title": "Dhaka, <span style=\"color:gray; font-weight: normal;\"> Bangladesh </span>"},
+        {"column": "Lagos", "title": "Lagos, <span style=\"color:gray; font-weight: normal;\">Nigeria</span>"},
+        {"column": "Paris", "title": "Paris, <span style=\"color:gray; font-weight: normal;\">France</span>"},
+        {"column": "Tokyo", "title": "Tokyo, <span style=\"color:gray; font-weight: normal;\">Japan</span>"},
+        {"column": "Beijing", "title": "Beijing, <span style=\"color:gray; font-weight: normal;\">China</span>"},
+        {"column": "Mumbai (Bombay)", "title": "Mumbai, <span style=\"color:gray; font-weight: normal;\">India</span>"},
+        {"column": "New York-Newark", "title": "New York/Newark, <span style=\"color:gray; font-weight: normal;\">U.S.</span>"},
+    ],
+    # Add text annotation to label the projection period
+    text_annotations=[
+        {
+            "text": "2025",
+            "x": "2023/01/01",
+            "y": 30000000,
+            "align": "tc",
+            "color": "#b73229",
+            "size": 14,
+            "bold": True,
+        },
+    ],
+    # Add range annotation to highlight projection period
+    range_annotations=[
+        {
+            "x0": "2018/01/01",
+            "x1": "2037/07/02",
+            "y0": 0,
+            "y1": 50000000,
+            "display": "range",
+            "color": "#888",
+            "opacity": 18,
+        },
+    ],
+)
+
+# Create the chart in Datawrapper
+chart.create()
+```
+
 ## Reference
 
 ```{eval-rst}

docs/user-guide/charts/scatter-plots.md

@@ -1,5 +1,130 @@
 # ScatterPlot
 
+This example, drawn from [Datawrapper's official documentation](https://www.datawrapper.de/charts/scatter-plot), demonstrates how to create a scatter plot showing the relationship between GDP per capita and life expectancy over time. The chart uses bubble size to represent population and features text annotations to label specific countries and years.
+
+<iframe title="Every country has a higher life expectancy now than in 1800" aria-label="Scatter Plot" id="datawrapper-chart-g9N3W" src="https://datawrapper.dwcdn.net/g9N3W/1/" scrolling="no" frameborder="0" style="width: 0; min-width: 100% !important; border: none;" height="731" data-external="1"></iframe><script type="text/javascript">window.addEventListener("message",function(a){if(void 0!==a.data["datawrapper-height"]){var e=document.querySelectorAll("iframe");for(var t in a.data["datawrapper-height"])for(var r,i=0;r=e[i];i++)if(r.contentWindow===a.source){var d=a.data["datawrapper-height"][t]+"px";r.style.height=d}}});</script>
+
+```python
+import pandas as pd
+import datawrapper as dw
+
+# Load life expectancy data from GitHub
+df = pd.read_csv(
+    "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/scatter/life-expectancy.csv",
+    sep="\t"
+)
+
+chart = dw.ScatterPlot(
+    # Chart title
+    title="Every country has a higher life expectancy now than in 1800",
+    # Introductory text explaining the visualization
+    intro="Gross domestic product per person adjusted for differences in purchasing power (in international 2011 dollars) vs life expectacy of newborns, for selected countries in 1800 and 2015. The size of the circle shows the population of the countries.",
+    # Data source attribution
+    source_name="Gapminder",
+    source_url="https://www.gapminder.org/data/",
+    # Author credit
+    byline="Lisa Charlotte Muth, Datawrapper",
+    # Data from pandas DataFrame
+    data=df,
+    # Define which columns to use for each dimension
+    x_column="GPD",
+    y_column="Health",
+    size_column="population",
+    label_column="country",
+    # Use logarithmic scale for x-axis (GDP)
+    x_log=True,
+    # Set custom range for axes
+    x_range=[200, ""],
+    y_range=[0, 94],
+    # Format axis labels
+    x_format="0a",  # Abbreviated format (e.g., "10k")
+    y_format="0a",
+    # Configure bubble size
+    size="dynamic",
+    max_size=60,
+    # Set opacity for better visibility of overlapping bubbles
+    opacity=0.6,
+    # Set base color for all points
+    base_color="#15607a",
+    # Set fixed plot height
+    plot_height_fixed=581,
+    # Disable automatic labeling (we'll add custom text annotations)
+    auto_labels=False,
+    # Custom tooltip format
+    tooltip_title='<big>{{ country }}</big> in <big>{{ FORMAT(year, "YYYY") }}</big>',
+    tooltip_body="""<table>
+  <tr>
+    <td>Life expectancy: &emsp; </td>
+    <td>GDP per capita:</td>
+  </tr>
+  <tr>
+    <td><b>{{ health }} years</b></td>
+    <td><b>{{ FORMAT(gdp, "0,0") }} Int'l$</b></td>
+  </tr>
+</table>""",
+    # Add text annotations to label years and key countries
+    text_annotations=[
+        {
+            "text": "1800",
+            "x": 156700,
+            "y": 45,
+            "align": "tr",
+            "dx": -14,
+            "dy": 13,
+            "bold": True,
+            "size": 18,
+        },
+        {
+            "text": "2015",
+            "x": 156700,
+            "y": 92,
+            "align": "tr",
+            "dx": -14,
+            "dy": 13,
+            "bold": True,
+            "size": 18,
+        },
+        {
+            "text": "China",
+            "x": "13398.7010",
+            "y": "76.1317",
+            "align": "mc",
+            "color": "#000000",
+            "size": 13,
+        },
+        {
+            "text": "India",
+            "x": "5997.2352",
+            "y": "67.2308",
+            "align": "mc",
+            "color": "#000000",
+            "size": 13,
+        },
+        {
+            "text": "Somalia",
+            "x": 620,
+            "y": 55.5,
+            "align": "tl",
+            "dx": 10,
+            "dy": -1,
+            "color": "#000000",
+            "size": 13,
+        },
+        {
+            "text": "US",
+            "x": "53787.2503",
+            "y": "79.0931",
+            "align": "mc",
+            "color": "#000000",
+            "size": 13,
+        },
+    ],
+)
+
+# Create the chart in Datawrapper
+chart.create()
+```
+
 ## Reference
 
 ```{eval-rst}

docs/user-guide/charts/stacked-bar-charts.md

@@ -1,5 +1,59 @@
 # StackedBarChart
 
+This example, drawn from [Datawrapper's official documentation](https://www.datawrapper.de/charts/stacked-bars), demonstrates how to create a diverging stacked bar chart showing trust levels in media reporting across different topics. The chart displays percentages with a [custom color scheme](https://colorbrewer2.org/#type=diverging&scheme=PRGn&n=5) to differentiate between trust levels, sorted by low trust values. It also includes value formatting.
+
+<iframe title="Trust in Media Reporting" aria-label="Stacked Bars" id="datawrapper-chart-j4JDS" src="https://datawrapper.dwcdn.net/j4JDS/1/" scrolling="no" frameborder="0" style="width: 0; min-width: 100% !important; border: none;" height="339" data-external="1"></iframe><script type="text/javascript">window.addEventListener("message",function(a){if(void 0!==a.data["datawrapper-height"]){var e=document.querySelectorAll("iframe");for(var t in a.data["datawrapper-height"])for(var r,i=0;r=e[i];i++)if(r.contentWindow===a.source){var d=a.data["datawrapper-height"][t]+"px";r.style.height=d}}});</script>
+
+```python
+import pandas as pd
+import datawrapper as dw
+
+# Load media trust data from GitHub
+df = pd.read_csv(
+    "https://raw.githubusercontent.com/chekos/Datawrapper/main/tests/samples/stacked_bar/media-trust.csv",
+    sep=";"
+)
+
+chart = dw.StackedBarChart(
+    # Chart title
+    title="Trust in Media Reporting",
+    # Introductory text explaining the context
+    intro="Trust in Media Reporting regarding widely reported topics of 2015",
+    # Data source attribution
+    source_name="Infratest dimap",
+    source_url="http://www.infratest-dimap.de/umfragen-analysen/bundesweit/umfragen/aktuell/wenig-vertrauen-in-medienberichterstattung/",
+    # Data from pandas DataFrame
+    data=df,
+    # Display values as percentages
+    stack_percentages=True,
+    # Format value labels as percentages
+    value_label_format="0%",
+    # Use diverging mode for better visual separation
+    value_label_mode="diverging",
+    # Sort bars by the "Low trust" column in descending order
+    sort_bars=True,
+    sort_by="Low trust",
+    reverse_order=True,
+    # Enable the color legend
+    show_color_key=True,
+    # Use thick bars for better visibility
+    thick_bars=True,
+    # Use block labels for category names
+    block_labels=True,
+    # Custom color mapping for each trust level
+    color_category={
+        "Very high trust": "#15607a",
+        "High trust": "#719aae",
+        "No answer": "#e8e8e8",
+        "Low trust": "#ff6954",
+        "Very low trust": "#c71e1d",
+    },
+)
+
+# Create the chart in Datawrapper
+chart.create()
+```
+
 ## Reference
 
 ```{eval-rst}