Reformat docstrings

packages/python/plotly/plotly/express/_chart_types.py

@@ -48,7 +48,8 @@ def scatter(
     height=None,
 ):
     """
-    In a scatter plot, each row of `data_frame` is represented by a symbol mark in 2D space.
+    In a scatter plot, each row of `data_frame` is represented by a symbol mark
+    in 2D space.
     """
     return make_figure(args=locals(), constructor=go.Scatter)
 
@@ -90,9 +91,9 @@ def density_contour(
     height=None,
 ):
     """
-    In a density contour plot, rows of `data_frame` are grouped together into contour marks to \
-    visualize the 2D distribution of an aggregate function `histfunc` (e.g. the count or sum) \
-    of the value `z`.
+    In a density contour plot, rows of `data_frame` are grouped together into
+    contour marks to visualize the 2D distribution of an aggregate function
+    `histfunc` (e.g. the count or sum) of the value `z`.
     """
     return make_figure(
         args=locals(),
@@ -145,9 +146,9 @@ def density_heatmap(
     height=None,
 ):
     """
-    In a density heatmap, rows of `data_frame` are grouped together into colored \
-    rectangular tiles to visualize the 2D distribution of an aggregate function \
-    `histfunc` (e.g. the count or sum) of the value `z`.
+    In a density heatmap, rows of `data_frame` are grouped together into
+    colored rectangular tiles to visualize the 2D distribution of an aggregate
+    function `histfunc` (e.g. the count or sum) of the value `z`.
     """
     return make_figure(
         args=locals(),
@@ -203,7 +204,8 @@ def line(
     height=None,
 ):
     """
-    In a 2D line plot, each row of `data_frame` is represented as vertex of a polyline mark in 2D space.
+    In a 2D line plot, each row of `data_frame` is represented as vertex of a
+    polyline mark in 2D space.
     """
     return make_figure(args=locals(), constructor=go.Scatter)
 
@@ -242,7 +244,9 @@ def area(
     height=None,
 ):
     """
-    In a stacked area plot, each row of `data_frame` is represented as vertex of a polyline mark in 2D space. The area between successive polylines is filled.
+    In a stacked area plot, each row of `data_frame` is represented as vertex
+    of a polyline mark in 2D space. The area between successive polylines is
+    filled.
     """
     return make_figure(
         args=locals(),
@@ -293,7 +297,8 @@ def bar(
     height=None,
 ):
     """
-    In a bar plot, each row of `data_frame` is represented as a rectangular mark.
+    In a bar plot, each row of `data_frame` is represented as a rectangular
+    mark.
     """
     return make_figure(
         args=locals(),
@@ -340,9 +345,10 @@ def histogram(
     height=None,
 ):
     """
-    In a histogram, rows of `data_frame` are grouped together into a rectangular mark to \
-    visualize the 1D distribution of an aggregate function `histfunc` (e.g. the count or sum) \
-    of the value `y` (or `x` if `orientation` is `'h'`).
+    In a histogram, rows of `data_frame` are grouped together into a
+    rectangular mark to visualize the 1D distribution of an aggregate function
+    `histfunc` (e.g. the count or sum) of the value `y` (or `x` if
+    `orientation` is `'h'`).
     """
     return make_figure(
         args=locals(),
@@ -393,8 +399,8 @@ def violin(
     height=None,
 ):
     """
-    In a violin plot, rows of `data_frame` are grouped together into a curved mark to \
-    visualize their distribution.
+    In a violin plot, rows of `data_frame` are grouped together into a curved
+    mark to visualize their distribution.
     """
     return make_figure(
         args=locals(),
@@ -444,8 +450,8 @@ def box(
     height=None,
 ):
     """
-    In a box plot, rows of `data_frame` are grouped together into a box-and-whisker mark to \
-    visualize their distribution.
+    In a box plot, rows of `data_frame` are grouped together into a
+    box-and-whisker mark to visualize their distribution.
     """
     return make_figure(
         args=locals(),
@@ -488,7 +494,8 @@ def strip(
     height=None,
 ):
     """
-    In a strip plot each row of `data_frame` is represented as a jittered mark within categories.
+    In a strip plot each row of `data_frame` is represented as a jittered mark
+    within categories.
     """
     return make_figure(
         args=locals(),
@@ -553,7 +560,8 @@ def scatter_3d(
     height=None,
 ):
     """
-    In a 3D scatter plot, each row of `data_frame` is represented by a symbol mark in 3D space.
+    In a 3D scatter plot, each row of `data_frame` is represented by a symbol
+    mark in 3D space.
     """
     return make_figure(args=locals(), constructor=go.Scatter3d)
 
@@ -599,7 +607,8 @@ def line_3d(
     height=None,
 ):
     """
-    In a 3D line plot, each row of `data_frame` is represented as vertex of a polyline mark in 3D space.
+    In a 3D line plot, each row of `data_frame` is represented as vertex of a
+    polyline mark in 3D space.
     """
     return make_figure(args=locals(), constructor=go.Scatter3d)
 
@@ -638,7 +647,8 @@ def scatter_ternary(
     height=None,
 ):
     """
-    In a ternary scatter plot, each row of `data_frame` is represented by a symbol mark in ternary coordinates.
+    In a ternary scatter plot, each row of `data_frame` is represented by a
+    symbol mark in ternary coordinates.
     """
     return make_figure(args=locals(), constructor=go.Scatterternary)
 
@@ -673,7 +683,8 @@ def line_ternary(
     height=None,
 ):
     """
-    In a ternary line plot, each row of `data_frame` is represented as vertex of a polyline mark in ternary coordinates.
+    In a ternary line plot, each row of `data_frame` is represented as vertex
+    of a polyline mark in ternary coordinates.
     """
     return make_figure(args=locals(), constructor=go.Scatterternary)
 
@@ -716,8 +727,8 @@ def scatter_polar(
     height=None,
 ):
     """
-    In a polar scatter plot, each row of `data_frame` is represented by a symbol mark in
-    polar coordinates.
+    In a polar scatter plot, each row of `data_frame` is represented by a
+    symbol mark in polar coordinates.
     """
     return make_figure(args=locals(), constructor=go.Scatterpolar)
 
@@ -757,7 +768,8 @@ def line_polar(
     height=None,
 ):
     """
-    In a polar line plot, each row of `data_frame` is represented as vertex of a polyline mark in polar coordinates.
+    In a polar line plot, each row of `data_frame` is represented as vertex of
+    a polyline mark in polar coordinates.
     """
     return make_figure(args=locals(), constructor=go.Scatterpolar)
 
@@ -791,7 +803,8 @@ def bar_polar(
     height=None,
 ):
     """
-    In a polar bar plot, each row of `data_frame` is represented as a wedge mark in polar coordinates.
+    In a polar bar plot, each row of `data_frame` is represented as a wedge
+    mark in polar coordinates.
     """
     return make_figure(
         args=locals(),
@@ -831,7 +844,8 @@ def choropleth(
     height=None,
 ):
     """
-    In a choropleth map, each row of `data_frame` is represented by a colored region mark on a map.
+    In a choropleth map, each row of `data_frame` is represented by a colored
+    region mark on a map.
     """
     return make_figure(
         args=locals(),
@@ -875,7 +889,8 @@ def scatter_geo(
     height=None,
 ):
     """
-    In a geographic scatter plot, each row of `data_frame` is represented by a symbol mark on a map.
+    In a geographic scatter plot, each row of `data_frame` is represented by a
+    symbol mark on a map.
     """
     return make_figure(
         args=locals(),
@@ -917,7 +932,8 @@ def line_geo(
     height=None,
 ):
     """
-    In a geographic line plot, each row of `data_frame` is represented as vertex of a polyline mark on a map.
+    In a geographic line plot, each row of `data_frame` is represented as
+    vertex of a polyline mark on a map.
     """
     return make_figure(
         args=locals(),
@@ -957,7 +973,8 @@ def scatter_mapbox(
     height=None,
 ):
     """
-    In a Mapbox scatter plot, each row of `data_frame` is represented by a symbol mark on a Mapbox map.
+    In a Mapbox scatter plot, each row of `data_frame` is represented by a
+    symbol mark on a Mapbox map.
     """
     return make_figure(args=locals(), constructor=go.Scattermapbox)
 
@@ -988,7 +1005,8 @@ def line_mapbox(
     height=None,
 ):
     """
-    In a Mapbox line plot, each row of `data_frame` is represented as vertex of a polyline mark on a Mapbox map.
+    In a Mapbox line plot, each row of `data_frame` is represented as vertex of
+    a polyline mark on a Mapbox map.
     """
     return make_figure(args=locals(), constructor=go.Scattermapbox)
 
@@ -1022,9 +1040,9 @@ def scatter_matrix(
     height=None,
 ):
     """
-    In a scatter plot matrix (or SPLOM), each row of `data_frame` is represented \
-    by a multiple symbol marks, one in each cell of a grid of 2D scatter plots, which \
-    plot each pair of `dimensions` against each other.
+    In a scatter plot matrix (or SPLOM), each row of `data_frame` is
+    represented by a multiple symbol marks, one in each cell of a grid of 2D
+    scatter plots, which plot each pair of `dimensions` against each other.
     """
     return make_figure(
         args=locals(), constructor=go.Splom, layout_patch=dict(dragmode="select")
@@ -1048,8 +1066,8 @@ def parallel_coordinates(
     height=None,
 ):
     """
-    In a parallel coordinates plot, each row of `data_frame` is represented \
-    by a polyline mark which traverses a set of parallel axes, one for each of the \
+    In a parallel coordinates plot, each row of `data_frame` is represented by
+    a polyline mark which traverses a set of parallel axes, one for each of the
     `dimensions`.
     """
     return make_figure(args=locals(), constructor=go.Parcoords)
@@ -1072,9 +1090,10 @@ def parallel_categories(
     height=None,
 ):
     """
-    In a parallel categories (or parallel sets) plot, each row of `data_frame` is \
-    grouped with other rows that share the same values of `dimensions` and then plotted \
-    as a polyline mark through a set of parallel axes, one for each of the `dimensions`.
+    In a parallel categories (or parallel sets) plot, each row of `data_frame`
+    is grouped with other rows that share the same values of `dimensions` and
+    then plotted as a polyline mark through a set of parallel axes, one for
+    each of the `dimensions`.
     """
     return make_figure(args=locals(), constructor=go.Parcats)
 

packages/python/plotly/plotly/express/_doc.py

@@ -1,7 +1,6 @@
 import inspect
+from textwrap import TextWrapper
 
-colref = "(string or int: name of column in `data_frame`, or pandas Series, or array_like object)"
-colref_list = "(list of string or int: names of columns in `data_frame`, or pandas Series, or array_like objects)"
 
 # TODO contents of columns
 # TODO explain categorical
@@ -11,377 +10,444 @@
 # TODO document "or `None`, default `None`" in various places
 # TODO standardize positioning and casing of 'default'
 
+colref_type = "str or int or Series or array-like"
+colref_desc = "Either a name of a column in `data_frame`, or a pandas Series or array_like object."
+colref_list_type = "list of str or int, or Series or array-like"
+colref_list_desc = (
+    "Either names of columns in `data_frame`, or pandas Series, or array_like objects"
+)
+
 docs = dict(
     data_frame=[
-        "A `pandas.DataFrame`, or a `NumPy` array or a dictionary",
-        "which are tranformed internally to `pandas.DataFrame`. This argument needs"
-        "to be passed for column names (and not keyword names) to be used.",
+        "DataFrame or array-like or dict",
+        "This argument needs to be passed for column names (and not keyword names) to be used.",
+        "Array-like and dict are tranformed internally to a pandas DataFrame.",
     ],
     x=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the x axis in cartesian coordinates.",
         "For horizontal `histogram`s, these values are used as inputs to `histfunc`.",
     ],
     y=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the y axis in cartesian coordinates.",
         "For vertical `histogram`s, these values are used as inputs to `histfunc`.",
     ],
     z=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the z axis in cartesian coordinates.",
         "For `density_heatmap` and `density_contour` these values are used as the inputs to `histfunc`.",
     ],
     a=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the a axis in ternary coordinates.",
     ],
     b=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the b axis in ternary coordinates.",
     ],
     c=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the c axis in ternary coordinates.",
     ],
     r=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the radial axis in polar coordinates.",
     ],
     theta=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks along the angular axis in polar coordinates.",
     ],
     lat=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks according to latitude on a map.",
     ],
     lon=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to position marks according to longitude on a map.",
     ],
     locations=[
-        colref,
-        "Values from this column or array_like are be interpreted according to `locationmode` and mapped to longitude/latitude.",
+        colref_type,
+        colref_desc,
+        "Values from this column or array_like are to be interpreted according to `locationmode` and mapped to longitude/latitude.",
     ],
     dimensions=[
-        "(list of strings, names of columns in `data_frame`)",
-        "Columns to be used in multidimensional visualization.",
+        "list of str",
+        "Names of columns in `data_frame` to be used in multidimensional visualization.",
     ],
     error_x=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to size x-axis error bars.",
         "If `error_x_minus` is `None`, error bars will be symmetrical, otherwise `error_x` is used for the positive direction only.",
     ],
     error_x_minus=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to size x-axis error bars in the negative direction.",
         "Ignored if `error_x` is `None`.",
     ],
     error_y=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to size y-axis error bars.",
         "If `error_y_minus` is `None`, error bars will be symmetrical, otherwise `error_y` is used for the positive direction only.",
     ],
     error_y_minus=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to size y-axis error bars in the negative direction.",
         "Ignored if `error_y` is `None`.",
     ],
     error_z=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to size z-axis error bars.",
         "If `error_z_minus` is `None`, error bars will be symmetrical, otherwise `error_z` is used for the positive direction only.",
     ],
     error_z_minus=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to size z-axis error bars in the negative direction.",
         "Ignored if `error_z` is `None`.",
     ],
     color=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign color to marks.",
     ],
-    opacity=["(number, between 0 and 1) Sets the opacity for markers."],
+    opacity=["float", "Value between 0 and 1. Sets the opacity for markers."],
     line_dash=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign dash-patterns to lines.",
     ],
     line_group=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to group rows of `data_frame` into lines.",
     ],
     symbol=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign symbols to marks.",
     ],
     size=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign mark sizes.",
     ],
     hover_name=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like appear in bold in the hover tooltip.",
     ],
     hover_data=[
-        colref_list,
+        colref_list_type,
+        colref_list_desc,
         "Values from these columns appear as extra data in the hover tooltip.",
     ],
     custom_data=[
-        colref_list,
+        colref_list_type,
+        colref_list_desc,
         "Values from these columns are extra data, to be used in widgets or Dash callbacks for example. This data is not user-visible but is included in events emitted by the figure (lasso selection etc.)",
     ],
     text=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like appear in the figure as text labels.",
     ],
     locationmode=[
-        "(string, one of 'ISO-3', 'USA-states', 'country names')",
+        "str",
+        "One of 'ISO-3', 'USA-states', or 'country names'",
         "Determines the set of locations used to match entries in `locations` to regions on the map.",
     ],
     facet_row=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign marks to facetted subplots in the vertical direction.",
     ],
     facet_col=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign marks to facetted subplots in the horizontal direction.",
     ],
     animation_frame=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to assign marks to animation frames.",
     ],
     animation_group=[
-        colref,
+        colref_type,
+        colref_desc,
         "Values from this column or array_like are used to provide object-constancy across animation frames: rows with matching `animation_group`s will be treated as if they describe the same object in each frame.",
     ],
     symbol_sequence=[
-        "(list of strings defining plotly.js symbols)",
+        "list of str",
+        "Strings should define valid plotly.js symbols.",
         "When `symbol` is set, values in that column are assigned symbols by cycling through `symbol_sequence` in the order described in `category_orders`, unless the value of `symbol` is a key in `symbol_map`.",
     ],
     symbol_map=[
-        "(dict with string keys and values that are strings defining plotly.js symbols, default `{}`)",
+        "dict with str keys and str values (default `{}`)",
+        "String values should define plotly.js symbols",
         "Used to override `symbol_sequence` to assign a specific symbols to marks corresponding with specific values.",
         "Keys in `symbol_map` should be values in the column denoted by `symbol`.",
     ],
     line_dash_map=[
-        "(dict with string keys and values that are strings defining plotly.js dash-patterns, default `{}`)"
+        "dict with str keys and str values (default `{}`)",
+        "Strings values define plotly.js dash-patterns.",
         "Used to override `line_dash_sequences` to assign a specific dash-patterns to lines corresponding with specific values.",
         "Keys in `line_dash_map` should be values in the column denoted by `line_dash`.",
     ],
     line_dash_sequence=[
-        "(list of strings defining plotly.js dash-patterns)",
+        "list of str",
+        "Strings should define valid plotly.js dash-patterns.",
         "When `line_dash` is set, values in that column are assigned dash-patterns by cycling through `line_dash_sequence` in the order described in `category_orders`, unless the value of `line_dash` is a key in `line_dash_map`.",
     ],
     color_discrete_sequence=[
-        "(list of valid CSS-color strings)",
+        "list of str",
+        "Strings should define valid CSS-colors.",
         "When `color` is set and the values in the corresponding column are not numeric, values in that column are assigned colors by cycling through `color_discrete_sequence` in the order described in `category_orders`, unless the value of `color` is a key in `color_discrete_map`.",
         "Various useful color sequences are available in the `plotly_express.colors` submodules, specifically `plotly_express.colors.qualitative`.",
     ],
     color_discrete_map=[
-        "(dict with string keys and values that are valid CSS-color strings, default `{}`)",
+        "dict with str keys and str values (default `{}`)",
+        "String values should define valid CSS-colors",
         "Used to override `color_discrete_sequence` to assign a specific colors to marks corresponding with specific values.",
         "Keys in `color_discrete_map` should be values in the column denoted by `color`.",
     ],
     color_continuous_scale=[
-        "(list of valid CSS-color strings)",
+        "list of str",
+        "Strings should define valid CSS-colors",
         "This list is used to build a continuous color scale when the column denoted by `color` contains numeric data.",
         "Various useful color scales are available in the `plotly_express.colors` submodules, specifically `plotly_express.colors.sequential`, `plotly_express.colors.diverging` and `plotly_express.colors.cyclical`.",
     ],
     color_continuous_midpoint=[
-        "(number, defaults to `None`)",
+        "number (default `None`)",
         "If set, computes the bounds of the continuous color scale to have the desired midpoint.",
         "Setting this value is recommended when using `plotly_express.colors.diverging` color scales as the inputs to `color_continuous_scale`.",
     ],
-    size_max=["(integer, default 20)", "Set the maximum mark size when using `size`."],
+    size_max=["int (default `20`)", "Set the maximum mark size when using `size`."],
     log_x=[
-        "(boolean, default `False`)",
+        "boolean (default `False`)",
         "If `True`, the x-axis is log-scaled in cartesian coordinates.",
     ],
     log_y=[
-        "(boolean, default `False`)",
+        "boolean (default `False`)",
         "If `True`, the y-axis is log-scaled in cartesian coordinates.",
     ],
     log_z=[
-        "(boolean, default `False`)",
+        "boolean (default `False`)",
         "If `True`, the z-axis is log-scaled in cartesian coordinates.",
     ],
     log_r=[
-        "(boolean, default `False`)",
+        "boolean (default `False`)",
         "If `True`, the radial axis is log-scaled in polar coordinates.",
     ],
     range_x=[
-        "(2-element list of numbers)",
+        "list of two numbers",
         "If provided, overrides auto-scaling on the x-axis in cartesian coordinates.",
     ],
     range_y=[
-        "(2-element list of numbers)",
+        "list of two numbers",
         "If provided, overrides auto-scaling on the y-axis in cartesian coordinates.",
     ],
     range_z=[
-        "(2-element list of numbers)",
+        "list of two numbers",
         "If provided, overrides auto-scaling on the z-axis in cartesian coordinates.",
     ],
     range_color=[
-        "(2-element list of numbers)",
+        "list of two numbers",
         "If provided, overrides auto-scaling on the continuous color scale.",
     ],
     range_r=[
-        "(2-element list of numbers)",
+        "list of two numbers",
         "If provided, overrides auto-scaling on the radial axis in polar coordinates.",
     ],
-    title=["(string)", "The figure title."],
+    title=["str", "The figure title."],
     template=[
-        "(string or Plotly.py template object)",
+        "str or Plotly.py template object",
         "The figure template name or definition.",
     ],
-    width=["(integer, default `None`)", "The figure width in pixels."],
-    height=["(integer, default `600`)", "The figure height in pixels."],
+    width=["int (default `None`)", "The figure width in pixels."],
+    height=["int (default `600`)", "The figure height in pixels."],
     labels=[
-        "(dict with string keys and string values, default `{}`)",
+        "dict with str keys and str values (default `{}`)",
         "By default, column names are used in the figure for axis titles, legend entries and hovers.",
         "This parameter allows this to be overridden.",
         "The keys of this dict should correspond to column names, and the values should correspond to the desired label to be displayed.",
     ],
     category_orders=[
-        "(dict with string keys and list-of-string values, default `{}`)",
+        "dict with str keys and list of str values (default `{}`)",
         "By default, in Python 3.6+, the order of categorical values in axes, legends and facets depends on the order in which these values are first encountered in `data_frame` (and no order is guaranteed by default in Python below 3.6).",
         "This parameter is used to force a specific ordering of values per column.",
         "The keys of this dict should correspond to column names, and the values should be lists of strings corresponding to the specific display order desired.",
     ],
     marginal=[
-        "(string, one of `'rug'`, `'box'`, `'violin'`, `'histogram'`)",
+        "str",
+        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
         "If set, a subplot is drawn alongside the main plot, visualizing the distribution.",
     ],
     marginal_x=[
-        "(string, one of `'rug'`, `'box'`, `'violin'`, `'histogram'`)",
+        "str",
+        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
         "If set, a horizontal subplot is drawn above the main plot, visualizing the x-distribution.",
     ],
     marginal_y=[
-        "(string, one of `'rug'`, `'box'`, `'violin'`, `'histogram'`)",
+        "str",
+        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
         "If set, a vertical subplot is drawn to the right of the main plot, visualizing the y-distribution.",
     ],
     trendline=[
-        "(string, one of `'ols'` or `'lowess'`, default `None`)",
+        "str",
+        "One of `'rug'`, `'box'`, `'violin'`, `'histogram'`.",
         "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.",
     ],
     trendline_color_override=[
-        "(string, valid CSS color)",
+        "str",
+        "Valid CSS color.",
         "If provided, and if `trendline` is set, all trendlines will be drawn in this color.",
     ],
     render_mode=[
-        "(string, one of `'auto'`, `'svg'` or `'webgl'`, default `'auto'`)",
+        "str",
+        "One of `'auto'`, `'svg'` or `'webgl'`, default `'auto'`",
         "Controls the browser API used to draw marks.",
         "`'svg`' is appropriate for figures of less than 1000 data points, and will allow for fully-vectorized output.",
         "`'webgl'` is likely necessary for acceptable performance above 1000 points but rasterizes part of the output. ",
         "`'auto'` uses heuristics to choose the mode.",
     ],
     direction=[
-        "(string, one of '`counterclockwise'`, `'clockwise'`. Default is `'clockwise'`)",
+        "str",
+        "One of '`counterclockwise'`, `'clockwise'`. Default is `'clockwise'`",
         "Sets the direction in which increasing values of the angular axis are drawn.",
     ],
     start_angle=[
-        "(integer, default is 90)",
+        "int (default `90`)",
         "Sets start angle for the angular axis, with 0 being due east and 90 being due north.",
     ],
     histfunc=[
-        "(string, one of `'count'`, `'sum'`, `'avg'`, `'min'`, `'max'`. Default is `'count'`)"
+        "str (default `'count'`)",
+        "One of `'count'`, `'sum'`, `'avg'`, `'min'`, `'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=[
-        "(string, one of `'percent'`, `'probability'`, `'density'`, `'probability density'`, default `None`)",
+        "str (default `None`)",
+        "One of `'percent'`, `'probability'`, `'density'`, `'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.",
         "If `'density'`, the output of `histfunc` for a given bin is divided by the size of the bin.",
         "If `'probability density'`, the output of `histfunc` for a given bin is normalized such that it corresponds to the probability that a random event whose distribution is described by the output of `histfunc` will fall into that bin.",
     ],
     barnorm=[
-        "(string, one of `'fraction'` or `'percent'`, default is `None`)",
+        "str (default `None`)",
+        "One of `'fraction'` or `'percent'`.",
         "If `'fraction'`, the value of each bar is divided by the sum of all values at that location coordinate.",
         "`'percent'` is the same but multiplied by 100 to show percentages.",
         "`None` will stack up all values at each location coordinate.",
     ],
     groupnorm=[
-        "(string, one of `'fraction'` or `'percent'`, default is `None`)",
+        "str (default `None`)",
+        "One of `'fraction'` or `'percent'`.",
         "If `'fraction'`, the value of each point is divided by the sum of all values at that location coordinate.",
         "`'percent'` is the same but multiplied by 100 to show percentages.",
         "`None` will stack up all values at each location coordinate.",
     ],
     barmode=[
-        "(string, one of `'group'`, `'overlay'` or `'relative'`. Default is `'relative'`)",
+        "str (default `'relative'`)",
+        "One of `'group'`, `'overlay'` or `'relative'`",
         "In `'relative'` mode, bars are stacked above zero for positive values and below zero for negative values.",
         "In `'overlay'` mode, bars are drawn on top of one another.",
         "In `'group'` mode, bars are placed beside each other.",
     ],
     boxmode=[
-        "(string, one of `'group'` or `'overlay'`. Default is `'group'`)",
+        "str (default `'group'`)",
+        "One of `'group'` or `'overlay'`",
         "In `'overlay'` mode, boxes are on drawn top of one another.",
         "In `'group'` mode, baxes are placed beside each other.",
     ],
     violinmode=[
-        "(string, one of `'group'` or `'overlay'`. Default is `'group'`)",
+        "str (default `'group'`)",
+        "One of `'group'` or `'overlay'`",
         "In `'overlay'` mode, violins are on drawn top of one another.",
         "In `'group'` mode, violins are placed beside each other.",
     ],
     stripmode=[
-        "(string, one of `'group'` or `'overlay'`. Default is `'group'`)",
+        "str (default `'group'`)",
+        "One of `'group'` or `'overlay'`",
         "In `'overlay'` mode, strips are on drawn top of one another.",
         "In `'group'` mode, strips are placed beside each other.",
     ],
-    zoom=["(integer between 0 and 20, default is 8)", "Sets map zoom level."],
+    zoom=["int (default `8`)", "Between 0 and 20.", "Sets map zoom level."],
     orientation=[
-        "(string, one of `'h'` for horizontal or `'v'` for vertical)",
-        "Default is `'v'`.",
+        "str (default `'v'`)",
+        "One of `'h'` for horizontal or `'v'` for vertical)",
     ],
     line_close=[
-        "(boolean, default `False`)",
+        "boolean (default `False`)",
         "If `True`, an extra line segment is drawn between the first and last point.",
     ],
-    line_shape=["(string, one of `'linear'` or `'spline'`)", "Default is `'linear'`."],
+    line_shape=["str (default `'linear'`)", "One of `'linear'` or `'spline'`."],
     scope=[
-        "(string, one of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, `'south america'`)"
-        "Default is `'world'` unless `projection` is set to `'albers usa'`, which forces `'usa'`."
+        "str (default `'world'`).",
+        "One of `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, `'south america'`)"
+        "Default is `'world'` unless `projection` is set to `'albers usa'`, which forces `'usa'`.",
     ],
     projection=[
-        "(string, 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'`)"
-        "Default depends on `scope`."
+        "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'`"
+        "Default depends on `scope`.",
+    ],
+    center=[
+        "dict",
+        "Dict keys are `'lat'` and `'lon'`",
+        "Sets the center point of the map.",
     ],
-    center=["(dict with `lat` and `lon` keys)", "Sets the center point of the map."],
     points=[
-        "(string or boolean, one of `'all'`, `'outliers'`, or `False`. Default is `'outliers'`)",
+        "str or boolean (default `'outliers'`)",
+        "One of `'all'`, `'outliers'`, or `False`.",
         "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",
     ],
-    box=[
-        "(boolean, default `False`)",
-        "If `True`, boxes are drawn inside the violins.",
-    ],
-    notched=["(boolean, default `False`)", "If `True`, boxes are drawn with notches."],
+    box=["boolean (default `False`)", "If `True`, boxes are drawn inside the violins."],
+    notched=["boolean (default `False`)", "If `True`, boxes are drawn with notches."],
     cumulative=[
-        "(boolean, default `False`)",
+        "boolean (default `False`)",
         "If `True`, histogram values are cumulative.",
     ],
-    nbins=["(positive integer)", "Sets the number of bins."],
-    nbinsx=["(positive integer)", "Sets the number of bins along the x axis."],
-    nbinsy=["(positive integer)", "Sets the number of bins along the y axis."],
+    nbins=["int", "Positive integer.", "Sets the number of bins."],
+    nbinsx=["int", "Positive integer.", "Sets the number of bins along the x axis."],
+    nbinsy=["int", "Positive integer.", "Sets the number of bins along the y axis."],
 )
 
 
 def make_docstring(fn):
-    result = (fn.__doc__ or "") + "\nArguments:\n"
-    for arg in inspect.getargspec(fn)[0]:
-        d = (
-            " ".join(docs[arg] or "")
-            if arg in docs
+    tw = TextWrapper(width=79, initial_indent="    ", subsequent_indent="    ")
+    result = (fn.__doc__ or "") + "\nParameters\n----------\n"
+    for param in inspect.getargspec(fn)[0]:
+        param_desc_list = docs[param][1:]
+        param_desc = (
+            tw.fill(" ".join(param_desc_list or ""))
+            if param in docs
             else "(documentation missing from map)"
         )
-        result += "    %s: %s\n" % (arg, d)
-    result += "Returns:\n"
+        param_type = docs[param][0]
+        result += "%s: %s\n%s\n" % (param, param_type, param_desc)
+    result += "\nReturns\n-------\n"
     result += "    A `Figure` object."
     return result

packages/python/plotly/plotly/subplots.py

@@ -120,7 +120,7 @@ def make_subplots(
         Empty strings ("") can be included in the list if no subplot title
         is desired in that space so that the titles are properly indexed.
 
-    specs: list of lists of dictionaries or None (default None)
+    specs: list of lists of dict or None (default None)
         Per subplot specifications of subplot type, row/column spanning, and
         spacing.
 
@@ -173,7 +173,7 @@ def make_subplots(
         - Note: Use 'horizontal_spacing' and 'vertical_spacing' to adjust
           the spacing in between the subplots.
 
-    insets: list of dictionaries or None (default None):
+    insets: list of dict or None (default None):
         Inset specifications.  Insets are subplots that overlay grid subplots
 
         - Each item in 'insets' is a dictionary.