From ab8f2c496a6d16ac8466c4d4631ec09059bd6629 Mon Sep 17 00:00:00 2001
From: alexpeters1208 <alexscottpeters1208@gmail.com>
Date: Thu, 25 Jul 2024 12:46:24 -0500
Subject: [PATCH] More polish

---
 plugins/plotly-express/docs/area.md           |  9 ++--
 plugins/plotly-express/docs/bar.md            |  9 ++--
 plugins/plotly-express/docs/box.md            | 13 +++--
 plugins/plotly-express/docs/candlestick.md    |  3 +-
 plugins/plotly-express/docs/funnel-area.md    |  8 +--
 plugins/plotly-express/docs/funnel.md         |  8 +--
 plugins/plotly-express/docs/histogram.md      | 23 ++++----
 plugins/plotly-express/docs/icicle.md         |  8 +--
 plugins/plotly-express/docs/line-3d.md        |  7 ++-
 plugins/plotly-express/docs/line-polar.md     |  8 +--
 plugins/plotly-express/docs/line-ternary.md   |  7 +--
 plugins/plotly-express/docs/line.md           |  7 ++-
 plugins/plotly-express/docs/ohlc.md           |  2 +-
 plugins/plotly-express/docs/pie.md            |  8 +--
 plugins/plotly-express/docs/scatter-3d.md     | 53 +++++++++----------
 plugins/plotly-express/docs/scatter-polar.md  |  8 +--
 .../plotly-express/docs/scatter-ternary.md    |  6 ++-
 plugins/plotly-express/docs/scatter.md        | 25 ++++-----
 plugins/plotly-express/docs/strip.md          |  7 ++-
 plugins/plotly-express/docs/sunburst.md       |  7 ++-
 plugins/plotly-express/docs/timeline.md       | 19 ++-----
 plugins/plotly-express/docs/treemap.md        |  8 +--
 plugins/plotly-express/docs/violin.md         | 21 ++++++--
 23 files changed, 132 insertions(+), 142 deletions(-)

diff --git a/plugins/plotly-express/docs/area.md b/plugins/plotly-express/docs/area.md
index 0bc491dd2..9eec82c68 100644
--- a/plugins/plotly-express/docs/area.md
+++ b/plugins/plotly-express/docs/area.md
@@ -14,7 +14,7 @@ Area plots are appropriate when the data contain a continuous response variable
 
 ### A basic area plot
 
-Visualize the relationship between two variables. In this case, an area plot is similar to a line plot.
+Visualize the relationship between two variables by passing each variable to the `x` and `y` arguments.
 
 ```python order=area_plot,usa_population
 import deephaven.plot.express as dx
@@ -23,7 +23,6 @@ gapminder = dx.data.gapminder()
 # subset to get a specific group
 usa_population = gapminder.where("country == `United States`")
 
-# create a basic area plot that tracks the trend of US population over time
 area_plot = dx.area(usa_population, x="year", y="pop")
 ```
 
@@ -31,15 +30,15 @@ area_plot = dx.area(usa_population, x="year", y="pop")
 
 Area plots are unique in that the y-axis demonstrates each groups' total contribution to the whole. Use the `by` argument to specify a grouping column.
 
-```python order=area_plot_multi,large_countries_population
+```python order=area_plot_group,large_countries_population
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
 # subset to get several countries to compare
 large_countries_population = gapminder.where("country in `United States`, `India`, `China`")
 
-# pass a grouping column to `by` to create a plot of cumulative population trend showing contribution from each country
-area_plot_multi = dx.area(large_countries_population, x="year", y="pop", by="country")
+# cumulative trend showing contribution from each group
+area_plot_group = dx.area(large_countries_population, x="year", y="pop", by="country")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/bar.md b/plugins/plotly-express/docs/bar.md
index 7e76e5764..267670598 100644
--- a/plugins/plotly-express/docs/bar.md
+++ b/plugins/plotly-express/docs/bar.md
@@ -14,17 +14,16 @@ Bar plots are appropriate when the data contain a continuous response variable t
 
 ### A basic bar plot
 
-Visualize the relationship between a continuous variable and a categorical or discrete variable.
+Visualize the relationship between a continuous variable and a categorical or discrete variable by passing each to the `x` and `y` arguments.
 
 ```python order=bar_plot,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
-# create a basic bar plot by specifying columns for the `x` and `y` axes
 bar_plot = dx.bar(tips, x="day", y="total_bill")
 ```
 
-Change the x-axis order by sorting the dataset by the categorical variable.
+Change the x-axis ordering by sorting the dataset by the categorical variable.
 
 ```python order=ordered_bar_plot,tips
 import deephaven.plot.express as dx
@@ -44,10 +43,10 @@ tips = dx.data.tips() # import a ticking version of the Tips dataset
 
 sorted_tips = tips.sort("day")
 
-# partition bars by smoker / non-smoker
+# group by smoker / non-smoker
 bar_plot_smoke = dx.bar(sorted_tips, x="day", y="total_bill", by="smoker")
 
-# partition bars by male / female
+# group by male / female
 bar_plot_sex = dx.bar(sorted_tips, x="day", y="total_bill", by="sex")
 ```
 
diff --git a/plugins/plotly-express/docs/box.md b/plugins/plotly-express/docs/box.md
index cf1f1fc3e..a5e778a4c 100644
--- a/plugins/plotly-express/docs/box.md
+++ b/plugins/plotly-express/docs/box.md
@@ -14,29 +14,28 @@ Box plots are appropriate when the data have a continuous variable of interest.
 
 ### A basic box plot
 
-Visualize the distribution of a single continuous variable using a box plot. Data points displayed as dots are candidates for being outliers.
+Visualize the distribution of a single variable by passing the column name to `x` or `y`.
 
-```python order=total_bill_plot,tips
+```python order=box_plot,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
-# create a basic box plot by specifying the variable of interest with `y`
-total_bill_plot = dx.box(tips, y="total_bill")
+box_plot = dx.box(tips, y="total_bill")
 ```
 
 ### Distributions for multiple groups
 
 Box plots are useful for comparing the distributions of two or more groups of data. Use the `by` argument to specify a grouping column.
 
-```python order=total_bill_smoke,total_bill_sex,tips
+```python order=box_plot_group_1,box_plot_group_2,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
 # total bill distribution by smoker / non-smoker
-total_bill_smoke = dx.box(tips, y="total_bill", by="smoker")
+box_plot_group_1 = dx.box(tips, y="total_bill", by="smoker")
 
 # total bill distribution by male / female
-total_bill_sex = dx.box(tips, y="total_bill", by="sex")
+box_plot_group_2 = dx.box(tips, y="total_bill", by="sex")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/candlestick.md b/plugins/plotly-express/docs/candlestick.md
index 04853874b..6125083d2 100644
--- a/plugins/plotly-express/docs/candlestick.md
+++ b/plugins/plotly-express/docs/candlestick.md
@@ -16,7 +16,7 @@ In a bullish (upward, typically shown as green) candlestick, the open is typical
 
 ### A basic candlestick plot
 
-Visualize the key summary statistics of a stock price as it evolves.
+Visualize the key summary statistics of a stock price as it evolves. Specify the instrument of interest with `x`, and pass the `open`, `high`, `low`, and `close` arguments the appropriate column names.
 
 ```python order=candlestick_plot,stocks_1min_ohlc,stocks
 import deephaven.plot.express as dx
@@ -36,7 +36,6 @@ stocks_1min_ohlc = stocks.update_view(
     by=["sym", "binnedTimestamp"],
 )
 
-# create a basic candlestick plot - the `open`, `high`, `low`, and `close` arguments must be specified
 candlestick_plot = dx.candlestick(
     stocks_1min_ohlc.where("sym == `DOG`"),
     x="binnedTimestamp",
diff --git a/plugins/plotly-express/docs/funnel-area.md b/plugins/plotly-express/docs/funnel-area.md
index f215aa006..63f5cb886 100644
--- a/plugins/plotly-express/docs/funnel-area.md
+++ b/plugins/plotly-express/docs/funnel-area.md
@@ -16,14 +16,14 @@ Funnel area plots are appropriate when the data contain a categorical variable w
 
 ### A basic funnel plot
 
-Visualize the trend in consecutive stages of a categorical variable.
+Visualize the trend in consecutive stages of a categorical variable by specifying the `names` and `values` arguments.
 
-```python order=marking_trend_percentage,marketing
+```python order=funnel_area_plot,marketing
 import deephaven.plot.express as dx
 marketing = dx.data.marketing()
 
-# create a basic funnel plot by specifying column names for `names` and `values`
-marketing_trend_percentage = dx.funnel_area(marketing, names="Stage", values="Count")
+# `Count` is the frequency/value column, and `Stage` is the category column
+funnel_area_plot = dx.funnel_area(marketing, names="Stage", values="Count")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/funnel.md b/plugins/plotly-express/docs/funnel.md
index 05c57ed83..bc83608f3 100644
--- a/plugins/plotly-express/docs/funnel.md
+++ b/plugins/plotly-express/docs/funnel.md
@@ -16,14 +16,14 @@ Funnel plots are appropriate when the data contain a categorical variable where
 
 ### A basic funnel plot
 
-Visualize the trend in consecutive stages of a categorical variable.
+Visualize the trend in consecutive stages of a categorical variable by specifying the `x` and `y` arguments.
 
-```python order=marketing_trend,marketing
+```python order=funnel_plot,marketing
 import deephaven.plot.express as dx
 marketing = dx.data.marketing()
 
-# create a basic funnel plot by specifying column names for `x` and `y`
-marketing_trend = dx.funnel(marketing, x="Count", y="Stage")
+# `Count` is the frequency/value column, and `Stage` is the category column
+funnel_plot = dx.funnel(marketing, x="Count", y="Stage")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/histogram.md b/plugins/plotly-express/docs/histogram.md
index a65912148..508890b65 100644
--- a/plugins/plotly-express/docs/histogram.md
+++ b/plugins/plotly-express/docs/histogram.md
@@ -14,22 +14,21 @@ Histograms are appropriate when the data contain a continuous variable of intere
 
 ### A basic histogram
 
-Visualize the distribution of a single continuous variable.
+Visualize the distribution of a single variable by passing the variable's name to the `x` or `y` arguments.
 
-```python order=setosa_sep_length,setosa,iris
+```python order=hist_plot,setosa,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # subset to get specific species
 setosa = iris.where("species == `setosa`")
 
-# create a basic histogram by passing the column of interest to `x`
-setosa_sep_length = dx.histogram(setosa, x="sepal_length")
+hist_plot = dx.histogram(setosa, x="sepal_length")
 ```
 
 Modify the bin size by setting `nbins` equal to the number of desired bins.
 
-```python order=setosa_sep_length,setosa,iris
+```python order=hist_20_bins,hist_3_bins,hist_8_bins,virginica,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
@@ -37,28 +36,28 @@ iris = dx.data.iris()
 virginica = iris.where("species == `virginica`")
 
 # too many bins will produce jagged, disconnected histograms
-virginica_20_bins = dx.histogram(setosa, x="sepal_length", nbins=20)
+hist_20_bins = dx.histogram(setosa, x="sepal_length", nbins=20)
 
 # too few bins will mask distributional information
-virginica_3_bins = dx.histogram(setosa, x="sepal_length", nbins=3)
+hist_3_bins = dx.histogram(setosa, x="sepal_length", nbins=3)
 
 # play with the `nbins` parameter to get a good visualization
-virginica_8_bins = dx.histogram(setosa, x="sepal_length", nbins=8)
+hist_8_bins = dx.histogram(setosa, x="sepal_length", nbins=8)
 ```
 
 ### Distributions of several groups
 
-Histograms can also be used to compare the distributional properties of different groups of data, though they may be a little harder to read than box plots or violin plots.
+Histograms can also be used to compare the distributional properties of different groups of data, though they may be a little harder to read than box plots or violin plots. Use the `by` argument to specify a grouping column.
 
-```python order=sep_length_multi,sep_length_multi_overlay,iris
+```python order=stacked_hist,overlay_hist,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # each bin may be stacked side-by-side for each group
-sep_length_multi = dx.histogram(iris, x="sepal_length", by="species")
+stacked_hist = dx.histogram(iris, x="sepal_length", by="species")
 
 # or, each bin may be overlaid with the others
-sep_length_multi_overlay = dx.histogram(iris, x="sepal_length", by="species", barmode="overlay")
+overlay_hist = dx.histogram(iris, x="sepal_length", by="species", barmode="overlay")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/icicle.md b/plugins/plotly-express/docs/icicle.md
index 91e65b288..2085d1542 100644
--- a/plugins/plotly-express/docs/icicle.md
+++ b/plugins/plotly-express/docs/icicle.md
@@ -14,9 +14,9 @@ Icicle plots are appropriate when the data have a hierarchical structure. Each l
 
 ### A basic icicle plot
 
-Visualize a hierarchical dataset as nested rectangles, with categories displayed left-to-right, and the size of each category displayed top-to-bottom.
+Visualize a hierarchical dataset as nested rectangles, with categories displayed left-to-right, and the size of each category displayed top-to-bottom. Use the `names` argument to specify the labels for each group, the `values` argument to specify the value column for each group, and the `parents` column to specify the root category of the chart.
 
-```python order=continent_population,gapminder_recent,gapminder
+```python order=icicle_plot,gapminder_recent,gapminder
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
@@ -26,10 +26,10 @@ gapminder_recent = (
     .last_by("country")
     .view(["continent", "pop"])
     .sum_by("continent")
+    .update("world = `world`")
 )
 
-# create a basic icicle plot by specifying the categories, the values of interest, and a single root 'world'
-continent_population = dx.icicle(gapminder_recent.update("world = `world`"), names="continent", values="pop", parents="world")
+icicle_plot = dx.icicle(gapminder_recent, names="continent", values="pop", parents="world")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/line-3d.md b/plugins/plotly-express/docs/line-3d.md
index 0c1038689..1e01645d8 100644
--- a/plugins/plotly-express/docs/line-3d.md
+++ b/plugins/plotly-express/docs/line-3d.md
@@ -19,9 +19,9 @@ Alternatives to 3D line plots include:
 
 ### A basic 3D line plot
 
-Visualize the relationship between three variables by specifying each spatial component. Click and drag on the resulting chart to rotate it for new perspectives.
+Visualize the relationship between three variables by specifying the `x`, `y`, and `z` arguments. Click and drag on the resulting chart to rotate it for new perspectives.
 
-```python order=spiral_plot,spiral
+```python order=line_plot_3D,spiral
 import deephaven.plot.express as dx
 from deephaven import time_table
 
@@ -30,8 +30,7 @@ spiral = time_table("PT0.01s").update_view(
     ["X = sin(ii / 100)", "Y = cos(ii / 100)", "Z = 4 * ii / 100"]
 )
 
-# create a basic 3d line plot by specifying `x`, `y`, and `z`
-spiral_plot = dx.line_3d(spiral, x="X", y="Y", z="Z")
+line_plot_3D = dx.line_3d(spiral, x="X", y="Y", z="Z")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/line-polar.md b/plugins/plotly-express/docs/line-polar.md
index 59a60cc2b..b1f819d0e 100644
--- a/plugins/plotly-express/docs/line-polar.md
+++ b/plugins/plotly-express/docs/line-polar.md
@@ -14,12 +14,14 @@ Polar line plots are appropriate when the data contain a continuous variable rep
 
 ### A basic polar line plot
 
-```python order=wind_line,wind
+Visualize a dataset in polar coordinates by providing the `r` and `theta` arguments. `theta` may be passed as a string of cardinal directions, as in this case. `theta` also supports the use of numeric types that may represent radians or degrees, depending on how the `range_theta` argument is supplied.
+
+```python order=polar_line_plot,wind
 import deephaven.plot.express as dx
 wind = dx.data.wind()
 
-# create a polar line plot by specifying `r` and `theta`. `by` is used to separate data by groups
-wind_line = dx.line_polar(wind, r="frequency", theta="direction", by="strength")
+# `by` is used to separate data by groups
+polar_line_plot = dx.line_polar(wind, r="frequency", theta="direction", by="strength")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/line-ternary.md b/plugins/plotly-express/docs/line-ternary.md
index f49d8ba82..5e50c32a9 100644
--- a/plugins/plotly-express/docs/line-ternary.md
+++ b/plugins/plotly-express/docs/line-ternary.md
@@ -14,12 +14,13 @@ Ternary line plots are appropriate when the data contain three interrelated mutu
 
 ### A basic ternary line plot
 
-```python order=election_line,election
+Visualize a ternary dataset by passing categorical variables to each of the `a`, `b`, and `c` arguments.
+
+```python order=ternary_line_plot,election
 import deephaven.plot.express as dx
 election = dx.data.election()
 
-# create a ternary line plot by passing the column names for the three points of the triangle to `a`, `b`, and `c`
-election_line = dx.line_ternary(election, a="Joly", b="Coderre", c="Bergeron")
+ternary_line_plot = dx.line_ternary(election, a="Joly", b="Coderre", c="Bergeron")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/line.md b/plugins/plotly-express/docs/line.md
index f36be64dc..6e5fe204c 100644
--- a/plugins/plotly-express/docs/line.md
+++ b/plugins/plotly-express/docs/line.md
@@ -14,7 +14,7 @@ Line plots are appropriate when the data contain a continuous response variable
 
 ### A basic line plot
 
-Visualize the relationship between two variables. Column names are passed in directly as `x` and `y`.
+Visualize the relationship between two variables by passing each variable to the `x` and `y` arguments.
 
 ```python order=line_plot,my_table
 import deephaven.plot.express as dx
@@ -23,20 +23,19 @@ my_table = dx.data.stocks()
 # subset data for just DOG transactions
 dog_prices = my_table.where("sym = `DOG`")
 
-# create a basic line plot by specifying the x and y column
 line_plot = dx.line(dog_prices, x="timestamp", y="price")
 ```
 
 ### Color line plot by group
 
-Create a line with a unique color for each group in the dataset.
+Create a line with a unique color for each group in the dataset using the `by` argument.
 
 ```python order=line_plot,mytable
 import deephaven.plot.express as dx
 my_table = dx.data.stocks()
 
 # each line represents a group and has a unique color
-line_plot = dx.line(my_table, x="timestamp", y="price", color="sym")
+line_plot = dx.line(my_table, x="timestamp", y="price", by="sym")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/ohlc.md b/plugins/plotly-express/docs/ohlc.md
index 748064a99..5a6fbf45d 100644
--- a/plugins/plotly-express/docs/ohlc.md
+++ b/plugins/plotly-express/docs/ohlc.md
@@ -14,7 +14,7 @@ In OHLC plots, each bar consists of a vertical line with small horizontal lines
 
 ### A basic OHLC plot
 
-Visualize the key summary statistics of a stock price as it evolves.
+Visualize the key summary statistics of a stock price as it evolves. Specify the instrument of interest with `x`, and pass the `open`, `high`, `low`, and `close` arguments the appropriate column names.
 
 ```python order=ohlc_plot,stocks_1min_ohlc,stocks
 import deephaven.plot.express as dx
diff --git a/plugins/plotly-express/docs/pie.md b/plugins/plotly-express/docs/pie.md
index 392e66fa5..84ab4483f 100644
--- a/plugins/plotly-express/docs/pie.md
+++ b/plugins/plotly-express/docs/pie.md
@@ -15,12 +15,13 @@ Pie plots do have some limitations. They become less effective when dealing with
 
 # A basic pie plot
 
-Visualize the contribution of each part to the whole, arranged clockwise from greatest to least contribution.
+Visualize the contribution of each part to the whole, arranged clockwise from greatest to least contribution. Pass the label column to the `names` argument, and the value column to the `values` argument.
 
-```python order=continent_population,gapminder_recent_pop,gapminder
+```python order=pie_plot,gapminder_recent_pop,gapminder
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
+# get table of most recent total population per continent
 gapminder_recent_pop = (
     gapminder
     .last_by("country")
@@ -28,8 +29,7 @@ gapminder_recent_pop = (
     .sum_by(["year", "month", "continent"])
 )
 
-# specify the labels for each slice with `names`, and the value corresponding to that label with `values`
-continent_population = dx.pie(gapminder_recent_pop, names="continent", values="pop")
+pie_plot = dx.pie(gapminder_recent_pop, names="continent", values="pop")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/scatter-3d.md b/plugins/plotly-express/docs/scatter-3d.md
index b2a2f11a7..e1a8af89e 100644
--- a/plugins/plotly-express/docs/scatter-3d.md
+++ b/plugins/plotly-express/docs/scatter-3d.md
@@ -14,14 +14,13 @@ A 3D scatter plot is a type of data visualization that displays data points in t
 
 ### A basic 3D scatter plot
 
-Visualize the relationship between three variables by specifying each spatial component. Click and drag on the resulting chart to rotate it for new perspectives.
+Visualize the relationship between three variables by specifying the `x`, `y`, and `z` arguments. Click and drag on the resulting chart to rotate it for new perspectives.
 
-```python order=iris_3d,iris
+```python order=scatter_plot_3D,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
-# create a basic scatter plot by specifying the `x`, `y`, and `z` arguments
-iris_3d = dx.scatter_3d(iris, x="sepal_width", y="sepal_length", z="petal_width")
+scatter_plot_3D = dx.scatter_3d(iris, x="sepal_width", y="sepal_length", z="petal_width")
 ```
 
 ### Size markers by a quantitative variable
@@ -30,53 +29,49 @@ Use the size of the markers in a 3D scatter plot to visualize a fourth quantitat
 
 The `size` argument interprets the values in the given column as pixel size, so you may consider scaling or normalizing these values before creating the bubble chart.
 
-```python order=iris_3d_bubble,iris
+```python order=bubble_plot_3D,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
-# pass the name of the additional variable to the `size` argument 
-iris_3d_bubble = dx.scatter_3d(iris, x="sepal_width", y="sepal_length", z="petal_width", size="petal_length")
+bubble_plot_3D = dx.scatter_3d(iris, x="sepal_width", y="sepal_length", z="petal_width", size="petal_length")
 ```
 
 ### Color markers by group
 
-Denote groups of data by using the color of the markers as group indicators.
+Denote groups of data by using the color of the markers as group indicators. Pass the grouping column to the `by` argument.
 
-```python order=iris_3d_groups,iris
+```python order=scatter_plot_3D_groups,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
-# use the `by` argument to color markers by group
-iris_3d_groups = dx.scatter_3d(iris, x="sepal_width", y="sepal_length", z="petal_width", by="species")
+scatter_plot_3D_groups = dx.scatter_3d(iris, x="sepal_width", y="sepal_length", z="petal_width", by="species")
 ```
 
-Customize these colors using the `color_discrete_sequence` argument. Any [CSS color name](https://www.w3schools.com/cssref/css_colors.php), hexadecimal color code, or set of RGB values will work.
+Customize these colors using the `color_discrete_sequence` or `color_discrete_map` arguments. Any [CSS color name](https://www.w3schools.com/cssref/css_colors.php), hexadecimal color code, or set of RGB values will work.
 
-```python order=iris_3d_custom_1,iris_3d_custom_2,iris_3d_custom_3,iris
+```python order=scatter_3D_custom_1,scatter_3D_custom_2,scatter_3D_custom_3,iris,iris_with_custom_colors
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # set custom colors using color_discrete_sequence
-iris_3d_custom_1 = dx.scatter_3d(
+scatter_3D_custom_1 = dx.scatter_3d(
     iris,
     x="sepal_width",
     y="sepal_length",
     z="petal_width",
-    # group colors by a column
-    color="species",
+    by="species",
     # A list of colors to sequentially apply to one or more series
     # The colors loop if there are more series than colors
     color_discrete_sequence=["salmon", "#fffacd", "rgb(100,149,237)"]
 )
 
 # use a dictionary to specify custom colors
-iris_3d_custom_2 = dx.scatter_3d(
+scatter_3D_custom_2 = dx.scatter_3d(
     iris,
     x="sepal_width",
     y="sepal_length",
     z="petal_width",
-    # group colors by a column
-    color="species",
+    by="species",
     # set each series to a specific color
     color_discrete_map={"virginica":"lemonchiffon", "setosa": "cornflowerblue", "versicolor":"#FA8173"}
 )
@@ -86,12 +81,12 @@ iris_with_custom_colors = iris.update(
     "example_colors = `rgb(` + Math.round(Math.random() * 255) + `,` + Math.round(Math.random() * 255) + `,`  + Math.round(Math.random() * 255) +`)`"
 )
 
-iris_3d_custom_3 = dx.scatter_3d(
+scatter_3D_custom_3 = dx.scatter_3d(
     iris_with_custom_colors,
     x="sepal_width",
     y="sepal_length",
     z="petal_width",
-    color="example_colors",
+    by="example_colors",
     # When set to `identity`, the column data passed to the
     # color parameter will used as the actual color
     color_discrete_map="identity"
@@ -100,36 +95,36 @@ iris_3d_custom_3 = dx.scatter_3d(
 
 ### Color markers by a continuous variable
 
-Markers can also be colored by a continuous value. Any of plotly's [built-in color scales](https://plotly.com/python/builtin-colorscales/) may be used.
+Markers can also be colored by a continuous value by specifying the `color_continuous_scale` argument. Any of plotly's [built-in color scales](https://plotly.com/python/builtin-colorscales/) may be used.
 
-```python order=iris_3d_color,iris
+```python order=scatter_3D_color,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
 # use the `color` argument to specify the value column, and the `color_continuous_scale` to specify the color scale
-iris_3d_color = dx.scatter_3d(
+scatter_3D_color = dx.scatter_3d(
     iris,
     x="sepal_width",
     y="sepal_length",
     z="petal_width",
-    color="petal_length",
+    by="petal_length",
     # use any plotly express built in color scale names
     color_continuous_scale="viridis"
 )
 ```
 
-Or, define your own custom color scale.
+Or, supply your own custom color scale to `color_continuous_scale`.
 
-```python order=iris_3d_color_custom,iris
+```python order=scatter_3D_custom_color,iris
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
-iris_3d_color_custom = dx.scatter_3d(
+scatter_3D_custom_color = dx.scatter_3d(
     iris,
     x="sepal_width",
     y="sepal_length",
     z="petal_width",
-    color="petal_length",
+    by="petal_length",
     # custom scale colors can be any valid browser css color
     color_continuous_scale=["lemonchiffon", "#FA8173", "rgb(201, 61, 44)"]
 )
diff --git a/plugins/plotly-express/docs/scatter-polar.md b/plugins/plotly-express/docs/scatter-polar.md
index 1f0da139e..7aab8fa69 100644
--- a/plugins/plotly-express/docs/scatter-polar.md
+++ b/plugins/plotly-express/docs/scatter-polar.md
@@ -14,14 +14,14 @@ Polar scatter plots are appropriate when the data contain a continuous variable
 
 ### A basic polar scatter plot
 
-Visualize a dataset in polar coordinates.
+Visualize a dataset in polar coordinates by providing the `r` and `theta` arguments. `theta` may be passed as a string of cardinal directions, as in this case. `theta` also supports the use of numeric types that may represent radians or degrees, depending on how the `range_theta` argument is supplied.
 
-```python order=wind_scatter,wind
+```python order=polar_scatter_plot,wind
 import deephaven.plot.express as dx
 wind = dx.data.wind()
 
-# create a polar scatter plot by specifying r and theta. `by` is used to separate data by groups
-wind_scatter = dx.scatter_polar(wind, r="frequency", theta="direction", by="strength")
+# `by` is used to separate data by groups
+polar_scatter_plot = dx.scatter_polar(wind, r="frequency", theta="direction", by="strength")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/scatter-ternary.md b/plugins/plotly-express/docs/scatter-ternary.md
index b3e2ef5b5..3614c3ff1 100644
--- a/plugins/plotly-express/docs/scatter-ternary.md
+++ b/plugins/plotly-express/docs/scatter-ternary.md
@@ -14,12 +14,14 @@ Ternary scatter plots are appropriate when the data contain three interrelated m
 
 ### A basic ternary scatter plot
 
-```python order=election_scatter,election
+Visualize a ternary dataset by passing categorical variables to each of the `a`, `b`, and `c` arguments.
+
+```python order=ternary_scatter_plot,election
 import deephaven.plot.express as dx
 election = dx.data.election()
 
 # create a ternary scatter plot by specifying the columns for the three points of the triangle
-election_scatter = dx.scatter_ternary(election, a="Joly", b="Coderre", c="Bergeron")
+ternary_scatter_plot = dx.scatter_ternary(election, a="Joly", b="Coderre", c="Bergeron")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/scatter.md b/plugins/plotly-express/docs/scatter.md
index c316eb320..e8742befe 100644
--- a/plugins/plotly-express/docs/scatter.md
+++ b/plugins/plotly-express/docs/scatter.md
@@ -47,7 +47,7 @@ iris = dx.data.iris()
 scatter_plot_groups = dx.scatter(iris, x="sepal_width", y="sepal_length", by="species")
 ```
 
-Customize these colors using the `color_discrete_sequence` argument. Any [CSS color name](https://www.w3schools.com/cssref/css_colors.php), hexadecimal color code, or set of RGB values will work.
+Customize these colors using the `color_discrete_sequence` or `color_discrete_map` arguments. Any [CSS color name](https://www.w3schools.com/cssref/css_colors.php), hexadecimal color code, or set of RGB values will work.
 
 ```python order=custom_colors_1,custom_colors_2,custom_colors_3,iris
 import deephaven.plot.express as dx
@@ -58,8 +58,7 @@ custom_colors_1 = dx.scatter(
     iris,
     x="sepal_width",
     y="sepal_length",
-    # group colors by a column
-    color="species",
+    by="species",
     # A list of colors to sequentially apply to one or more series
     # The colors loop if there are more series than colors
     color_discrete_sequence=["salmon", "#fffacd", "rgb(100,149,237)"]
@@ -70,8 +69,7 @@ custom_colors_2 = dx.scatter(
     iris,
     x="sepal_width",
     y="sepal_length",
-    # group colors by a column
-    color="species",
+    by="species",
     # set each series to a specific color
     color_discrete_map={"virginica":"lemonchiffon", "setosa": "cornflowerblue", "versicolor":"#FA8173"}
 )
@@ -85,7 +83,7 @@ custom_colors_3 = dx.scatter(
     iris_with_custom_colors,
     x="sepal_width",
     y="sepal_length",
-    color="example_colors",
+    by="example_colors",
     # When set to `identity`, the column data passed to the
     # color parameter will used as the actual color
     color_discrete_map="identity"
@@ -94,7 +92,7 @@ custom_colors_3 = dx.scatter(
 
 ### Color markers by a continuous variable
 
-Markers can also be colored by a continuous value using the `color` and `color_continuous_scale` arguments. Any of plotly's [built-in color scales](https://plotly.com/python/builtin-colorscales/) may be used.
+Markers can also be colored by a continuous value by specifying the `color_continuous_scale` argument. Any of plotly's [built-in color scales](https://plotly.com/python/builtin-colorscales/) may be used.
 
 ```python order=scatter_plot_conts,iris
 import deephaven.plot.express as dx
@@ -104,7 +102,7 @@ scatter_plot_conts = dx.scatter(
     iris,
     x="sepal_width",
     y="sepal_length",
-    color="petal_length",
+    by="petal_length",
     # use any plotly express built in color scale names
     color_continuous_scale="viridis"
 )
@@ -120,7 +118,7 @@ custom_colors_conts = dx.scatter_3d(
     iris,
     x="sepal_width",
     y="sepal_length",
-    color="petal_length",
+    by="petal_length",
     # custom scale colors can be any valid browser css color
     color_continuous_scale=["lemonchiffon", "#FA8173", "rgb(201, 61, 44)"]
 )
@@ -139,7 +137,7 @@ scatter_plot_symbol_1 = dx.scatter(
     iris,
     x="sepal_width",
     y="sepal_length",
-    color="species",
+    by="species",
     # Assign symbols by group, shown using default symbol_sequence
     symbol="species"
 )
@@ -158,7 +156,7 @@ scatter_plot_symbol_3 = dx.scatter(
     iris,
     x="sepal_width",
     y="sepal_length",
-    color="species",
+    by="species",
     # Using a map for symbols by value
     symbol="species",
     symbol_map={"setosa":"cross", "versicolor":"pentagon", "virginica":"star"}
@@ -285,8 +283,7 @@ scatter_stocks = dx.scatter(
     stocks_table,
     x="timestamp",
     y="price",
-    # Parition color by sym
-    color="sym",
+    by="sym",
     # Apply each trace to a different axis
     yaxis_sequence=[1, 2],
     # Label each axis, where order is by first appearence in the data
@@ -354,7 +351,7 @@ scatter_as_markers = dx.layer(
         iris,
         x="timestamp",
         y="petal_length",
-        color="species",
+        by="species",
     ),
 )
 ```
diff --git a/plugins/plotly-express/docs/strip.md b/plugins/plotly-express/docs/strip.md
index 8f2dc703c..690cffc19 100644
--- a/plugins/plotly-express/docs/strip.md
+++ b/plugins/plotly-express/docs/strip.md
@@ -14,14 +14,13 @@ Strip plots are appropriate when the data contain a continuous variable of inter
 
 ### A basic strip plot
 
-Visualize the distributions of several groups of data at once. Specify the grouping column with the `by` argument.
+Visualize the distribution of a continuous variable by specifying the `x` or `y` arguments. Specify the grouping column with the `by` argument.
 
-```python order=bill_distr,tips
+```python order=strip_plot,tips
 import deephaven.plot.express as dx
 tips = dx.data.tips()
 
-# create a strip plot by specifying the variable of interest
-bill_distr = dx.strip(tips, x="total_bill", by="day", color_discrete_sequence=["lightgreen", "lightblue", "goldenrod", "lightcoral"])
+strip_plot = dx.strip(tips, x="total_bill", by="day", color_discrete_sequence=["lightgreen", "lightblue", "goldenrod", "lightcoral"])
 ```
 
 > [!NOTE]
diff --git a/plugins/plotly-express/docs/sunburst.md b/plugins/plotly-express/docs/sunburst.md
index 254dd22c2..1291ac90f 100644
--- a/plugins/plotly-express/docs/sunburst.md
+++ b/plugins/plotly-express/docs/sunburst.md
@@ -14,9 +14,9 @@ Sunburst plots are appropriate when the data have a hierarchical structure. Each
 
 ### A basic sunburst plot
 
-Visualize a hierarchical dataset as concentric circles, with the size of each group decreasing in a counter-clockwise fashion.
+Visualize a hierarchical dataset as concentric circles, with the size of each group decreasing in a counter-clockwise fashion. Use the `names` argument to specify the labels for each group, the `values` argument to specify the value column for each group, and the `parents` column to specify the root category of the chart.
 
-```python order=continent_population,gapminder_recent,gapminder
+```python order=sunburst_plot,gapminder_recent,gapminder
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
@@ -29,8 +29,7 @@ gapminder_recent = (
     .update("world = `world`")
 )
 
-# create a basic sunburst plot by specifying the categories, the values of interest, and a single root 'world'
-continent_population = dx.sunburst(gapminder_recent, names="continent", values="pop", parents="world")
+sunburst_plot = dx.sunburst(gapminder_recent, names="continent", values="pop", parents="world")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/timeline.md b/plugins/plotly-express/docs/timeline.md
index 3fba11ff6..56ae08346 100644
--- a/plugins/plotly-express/docs/timeline.md
+++ b/plugins/plotly-express/docs/timeline.md
@@ -8,26 +8,13 @@ A timeline plot is appropriate when the data contain a categorical variable whos
 
 ### A basic timeline plot
 
-Visualize the amount of time that each category in a column met a specific criteria.
+Visualize the amount of time that each category in a column met a specific criteria. Pass the start and end timestamp columns to the `x_start` and `x_end` arguments, and category column to the `y` arguments.
 
-```python order=jobs_tracking
+```python order=timeline_plot,jobs
 import deephaven.plot.express as dx
 jobs = dx.data.jobs()
 
-# create a basic timeline plot by specifying the start time column, end time column, and y-value column
-jobs_tracking = dx.timeline(jobs, x_start="StartTime", x_end="EndTime", y="Job")
-```
-
-### Color bars by a categorical variable
-
-Use an additional categorical variable to color the bars.
-
-```python order=jobs_tracking
-import deephaven.plot.express as dx
-jobs = dx.data.jobs()
-
-# the `by` argument is used to color the bars by another categorical variable
-jobs_resource_tracking = dx.timeline(jobs, x_start="StartTime", x_end="EndTime", y="Job", by="Resource")
+timeline_plot = dx.timeline(jobs, x_start="StartTime", x_end="EndTime", y="Job")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/treemap.md b/plugins/plotly-express/docs/treemap.md
index 7268f20e6..f197428b7 100644
--- a/plugins/plotly-express/docs/treemap.md
+++ b/plugins/plotly-express/docs/treemap.md
@@ -14,7 +14,9 @@ Treemap plots are appropriate when the data have a hierarchical structure. Each
 
 ### A basic treemap plot
 
-```python order=continent_population,gapminder_recent,gapminder
+Visualize a hierarchical dataset as nested rectangles, with the size of each rectangle corresponding to a value for a particular group. Use the `names` argument to specify the labels for each group, the `values` argument to specify the value column for each group, and the `parents` column to specify the root category of the chart.
+
+```python order=treemap_plot,gapminder_recent,gapminder
 import deephaven.plot.express as dx
 gapminder = dx.data.gapminder()
 
@@ -26,8 +28,8 @@ gapminder_recent = (
     .sum_by("continent")
     .update("world = `world`")
 )
-# create a basic treemap plot by specifying the categories, the values of interest, and a single root 'world'
-continent_population = dx.treemap(gapminder_recent, names="continent", values="pop", parents="world")
+
+treemap_plot = dx.treemap(gapminder_recent, names="continent", values="pop", parents="world")
 ```
 
 ## API Reference
diff --git a/plugins/plotly-express/docs/violin.md b/plugins/plotly-express/docs/violin.md
index b3430c350..337358b81 100644
--- a/plugins/plotly-express/docs/violin.md
+++ b/plugins/plotly-express/docs/violin.md
@@ -14,14 +14,27 @@ Violin plots are appropriate when the data contain a continuous variable of inte
 
 ### A basic violin plot
 
-Visualize the distribution of a continuous variable, for each group in a grouping column.
+Visualize the distribution of a continuous variable. Pass the name of the variable to the `x` or `y` arguments.
 
-```python order=sepal_length_distribution,iris
+```python order=violin_plot,versicolor
 import deephaven.plot.express as dx
 iris = dx.data.iris()
 
-# create a basic violin plot, specifying `x` will plot the violins horizontally, while specifying `y` will plot them vertically
-sepal_length_distribution = dx.violin(iris, x="sepal_length", by="species")
+# subset to get a specific group
+versicolor = iris.where("species == `versicolor`")
+
+violin_plot = dx.violin(versicolor, x="sepal_length")
+```
+
+### Distributions for multiple groups
+
+Use the `by` argument to visualize distributions for each group in a grouping column.
+
+```python order=violin_plot_group,iris
+import deephaven.plot.express as dx
+iris = dx.data.iris()
+
+violin_plot_group = dx.violin(iris, x="sepal_length", by="species")
 ```
 
 ## API Reference