Docstring touchups (#1866)

* Reduce line width to prevent wrapping in Jupyter Notebook help dialog

* Correct trendline docstring

* Unify language in "one of" docstrings

* Mention "suspectedoutliers" as a legal argument to the points parameter

This already shows up in the error message when passing "points" an illegal argument

* Document extension of whiskers when no sample points are plotted

The docstring already mentions that the points parameter can be used to control the whisker length, but it does not document how which lead to #522

* Document box and whisker ranges

* Mention whisker extension at one more place

* Add newline in boxplot description

Author: joelostblom

Diff for: packages/python/plotly/plotly/express/_chart_types.py

@@ -461,6 +461,12 @@ def box(
     """
     In a box plot, rows of `data_frame` are grouped together into a
     box-and-whisker mark to visualize their distribution.
+
+    Each box spans from quartile 1 (Q1) to quartile 3 (Q3). The
+    second quartile (Q2) is marked by a line inside the box. By
+    default, the whiskers correspond to the box' edges +/- 1.5
+    times the interquartile range (IQR: Q3-Q1), see "points" for
+    other options.
     """
     return make_figure(
         args=locals(),

Diff for: packages/python/plotly/plotly/express/_doc.py

@@ -302,22 +302,22 @@
     ],
     marginal=[
         "str",
-        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
+        "One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`.",
         "If set, a subplot is drawn alongside the main plot, visualizing the distribution.",
     ],
     marginal_x=[
         "str",
-        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
+        "One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`.",
         "If set, a horizontal subplot is drawn above the main plot, visualizing the x-distribution.",
     ],
     marginal_y=[
         "str",
-        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
+        "One of `'rug'`, `'box'`, `'violin'`, or `'histogram'`.",
         "If set, a vertical subplot is drawn to the right of the main plot, visualizing the y-distribution.",
     ],
     trendline=[
         "str",
-        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
+        "One of `'ols'` or `'lowess'`.",
         "If `'ols'`, an Ordinary Least Squares regression line will be drawn for each discrete-color/symbol group.",
         "If `'lowess`', a Locally Weighted Scatterplot Smoothing line will be drawn for each discrete-color/symbol group.",
     ],
@@ -336,7 +336,7 @@
     ],
     direction=[
         "str",
-        "One of '`counterclockwise'`, `'clockwise'`. Default is `'clockwise'`",
+        "One of '`counterclockwise'` or `'clockwise'`. Default is `'clockwise'`",
         "Sets the direction in which increasing values of the angular axis are drawn.",
     ],
     start_angle=[
@@ -345,15 +345,15 @@
     ],
     histfunc=[
         "str (default `'count'`)",
-        "One of `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`."
+        "One of `'count'`, `'sum'`, `'avg'`, `'min'`, or `'max'`."
         "Function used to aggregate values for summarization (note: can be normalized with `histnorm`).",
         "The arguments to this function for `histogram` are the values of `y` if `orientation` is `'v'`,",
         "otherwise the arguements are the values of `x`.",
         "The arguments to this function for `density_heatmap` and `density_contour` are the values of `z`.",
     ],
     histnorm=[
         "str (default `None`)",
-        "One of `'percent'`, `'probability'`, `'density'`, `'probability density'`",
+        "One of `'percent'`, `'probability'`, `'density'`, or `'probability density'`",
         "If `None`, the output of `histfunc` is used as is.",
         "If `'probability'`, the output of `histfunc` for a given bin is divided by the sum of the output of `histfunc` for all bins.",
         "If `'percent'`, the output of `histfunc` for a given bin is divided by the sum of the output of `histfunc` for all bins and multiplied by 100.",
@@ -411,12 +411,12 @@
     line_shape=["str (default `'linear'`)", "One of `'linear'` or `'spline'`."],
     scope=[
         "str (default `'world'`).",
-        "One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, `'south america'`)"
+        "One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, or `'south america'`)"
         "Default is `'world'` unless `projection` is set to `'albers usa'`, which forces `'usa'`.",
     ],
     projection=[
         "str ",
-        "One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, `'albers usa'`, `'winkel tripel'`, `'aitoff'`, `'sinusoidal'`"
+        "One of `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, `'albers usa'`, `'winkel tripel'`, `'aitoff'`, or `'sinusoidal'`"
         "Default depends on `scope`.",
     ],
     center=[
@@ -426,10 +426,12 @@
     ],
     points=[
         "str or boolean (default `'outliers'`)",
-        "One of `'all'`, `'outliers'`, or `False`.",
+        "One of `'outliers'`, `'suspectedoutliers'`, `'all'`, or `False`.",
+        "If `'outliers'`, only the sample points lying outside the whiskers are shown.",
+        "If `'suspectedoutliers'`, all outlier points are shown and those less than 4*Q1-3*Q3 or greater than 4*Q3-3*Q1 are highlighted with the marker's `'outliercolor'`.",
         "If `'outliers'`, only the sample points lying outside the whiskers are shown.",
         "If `'all'`, all sample points are shown.",
-        "If `False`, no sample points are shown",
+        "If `False`, no sample points are shown and the whiskers extend to the full range of the sample.",
     ],
     box=["boolean (default `False`)", "If `True`, boxes are drawn inside the violins."],
     notched=["boolean (default `False`)", "If `True`, boxes are drawn with notches."],
@@ -444,7 +446,7 @@
 
 
 def make_docstring(fn):
-    tw = TextWrapper(width=79, initial_indent="    ", subsequent_indent="    ")
+    tw = TextWrapper(width=77, initial_indent="    ", subsequent_indent="    ")
     result = (fn.__doc__ or "") + "\nParameters\n----------\n"
     for param in inspect.getargspec(fn)[0]:
         param_desc_list = docs[param][1:]

Diff for: packages/python/plotly/plotly/graph_objs/__init__.py

@@ -5533,7 +5533,8 @@ def points(self):
         are shown and points either less than 4*Q1-3*Q3 or greater than
         4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all
         sample points are shown If False, only the violins are shown
-        with no sample points
+        with no sample points and the whiskers extend to the range of the
+        sample.
 
         The 'points' property is an enumeration that may be specified as:
           - One of the following enumeration values:
@@ -6278,7 +6279,7 @@ def _prop_descriptions(self):
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the violins are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         scalegroup
             If there are multiple violins that should be sized
             according to to some metric (see `scalemode`), link
@@ -6610,7 +6611,7 @@ def __init__(
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the violins are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         scalegroup
             If there are multiple violins that should be sized
             according to to some metric (see `scalemode`), link
@@ -83296,7 +83297,8 @@ def boxpoints(self):
         are shown and points either less than 4*Q1-3*Q3 or greater than
         4*Q3-3*Q1 are highlighted (see `outliercolor`) If "all", all
         sample points are shown If False, only the box(es) are shown
-        with no sample points
+        with no sample points and the whiskers extend to the range of the
+        sample.
 
         The 'boxpoints' property is an enumeration that may be specified as:
           - One of the following enumeration values:
@@ -84562,7 +84564,7 @@ def _prop_descriptions(self):
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the box(es) are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         customdata
             Assigns extra data each datum. This may be useful when
             listening to hover, click and selection events. Note
@@ -84868,7 +84870,7 @@ def __init__(
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the box(es) are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         customdata
             Assigns extra data each datum. This may be useful when
             listening to hover, click and selection events. Note

Diff for: packages/python/plotly/plotly/graph_objs/_figure.py

@@ -1613,7 +1613,7 @@ def add_box(
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the box(es) are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         customdata
             Assigns extra data each datum. This may be useful when
             listening to hover, click and selection events. Note
@@ -14865,7 +14865,7 @@ def add_violin(
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the violins are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         scalegroup
             If there are multiple violins that should be sized
             according to to some metric (see `scalemode`), link

Diff for: packages/python/plotly/plotly/graph_objs/_figurewidget.py

@@ -1613,7 +1613,7 @@ def add_box(
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the box(es) are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         customdata
             Assigns extra data each datum. This may be useful when
             listening to hover, click and selection events. Note
@@ -14865,7 +14865,7 @@ def add_violin(
             or greater than 4*Q3-3*Q1 are highlighted (see
             `outliercolor`) If "all", all sample points are shown
             If False, only the violins are shown with no sample
-            points
+            points and the whiskers extend to the range of the sample.
         scalegroup
             If there are multiple violins that should be sized
             according to to some metric (see `scalemode`), link