Merge pull request #4294 from plotly/next-release-docs

Next release docs updates + upgrade plotly.js version

Author: LiamConnors

Diff for: CHANGELOG.md

@@ -6,7 +6,10 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## UNRELEASED
 
 ### Updated
-- Updated Plotly.js from version 2.24.1 to version 2.24.2. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2242----2023-06-09) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module.
+- Updated Plotly.js from version 2.24.1 to version 2.25.2. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2252----2023-08-11) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+  -  Add "Equal Earth" projection to geo subplots [[#6670](https://github.com/plotly/plotly.js/pull/6670)],
+   with thanks to @apparebit for the contribution!
+  - Add options to include legends for shapes and `newshape` [[#6653](https://github.com/plotly/plotly.js/pull/6653)]
 - `px` methods now accept data-frame-like objects that support a [dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), such as polars, vaex, modin etc. This protocol has priority on `to_pandas` call, but will only be used if pandas>=2.0.2 is installed in the environment.
 - `px` methods now accept data-frame-like objects that support a `toPandas()` method, such as Spark DataFrames, or a `to_pandas_df()` method, such as Vaex DataFrames.
 

Diff for: doc/python/legend.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.6
+      jupytext_version: 1.14.7
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.11
+    version: 3.10.4
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -35,7 +35,7 @@ jupyter:
 
 ### Trace Types, Legends and Color Bars
 
-[Traces](/python/figure-structure) of most types can be optionally associated with a single legend item in the [legend](/python/legend/). Whether or not a given trace appears in the legend is controlled via the `showlegend` attribute. Traces which are their own subplots (see above) do not support this, with the exception of traces of type `pie` and `funnelarea` for which every distinct color represented in the trace gets a separate legend item. Users may show or hide traces by clicking or double-clicking on their associated legend item. Traces that support legend items also support the `legendgroup` attribute, and all traces with the same legend group are treated the same way during click/double-click interactions.
+[Traces](/python/figure-structure) of most types and shapes can be optionally associated with a single legend item in the [legend](/python/legend/). Whether or not a given trace or shape appears in the legend is controlled via the `showlegend` attribute. Traces which are their own subplots (see above) do not support this, with the exception of traces of type `pie` and `funnelarea` for which every distinct color represented in the trace gets a separate legend item. Users may show or hide traces by clicking or double-clicking on their associated legend item. Traces that support legend items and shapes also support the `legendgroup` attribute, and all traces and shapes with the same legend group are treated the same way during click/double-click interactions.
 
 The fact that legend items are linked to traces means that when using [discrete color](/python/discrete-color/), a figure must have one trace per color in order to get a meaningful legend. [Plotly Express has robust support for discrete color](/python/discrete-color/) to make this easy.
 
@@ -97,26 +97,66 @@ fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1]))
 fig.show()
 ```
 
-*New in v5.0*
+*New in 5.16*
 
-The `legendrank` attribute of a trace can be used to control its placement within the legend, without regard for its placement in the `data` list.
+If you have shapes that are configured to appear in a legend, these are displayed after all traces:
 
-The default `legendrank` for traces is 1000 and ties are broken as described above, meaning that any trace can be pulled up to the top if it is the only one with a legend rank less than 1000 and pushed to the bottom if it is the only one with a rank greater than 1000.
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1, 2]))
+fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2, 1]))
+fig.add_shape(
+    name="first shape",
+    showlegend=True,
+    type="rect",
+    xref="paper",
+    line=dict(dash="dash"),
+    x0=0.85,
+    x1=0.95,
+    y0=0,
+    y1=1.5,
+)
+fig.add_trace(go.Bar(name="third", x=["a", "b"], y=[1, 2]))
+fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2, 1]))
+
+fig.show()
+
+```
+
+The `legendrank` attribute of a trace or shape can be used to control its placement in the legend.
+The default `legendrank` for traces and shapes is 1000. When all traces and shapes have the same `legendrank`, traces appear in the order they appear in the data, followed by shapes in the order they are defined.
+
+Any trace or shape can be pulled up to the top of the legend if it is the only one with a legend rank less than 1000 and pushed to the bottom if it is the only one with a rank greater than 1000.
+
+In this example, we add a `legendrank` for each trace and shape, giving the shape the lowest rank so it appears first, and moving the first trace defined to the bottom of the legend by giving it the highest rank.
 
 ```python
 import plotly.graph_objects as go
 
 fig = go.Figure()
-fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1], legendrank=4))
-fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2,1], legendrank=2))
-fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1,2], legendrank=1))
+fig.add_trace(go.Bar(name="fourth", x=["a", "b"], y=[2,1], legendrank=5))
+fig.add_trace(go.Bar(name="second", x=["a", "b"], y=[2,1], legendrank=4))
+fig.add_trace(go.Bar(name="first", x=["a", "b"], y=[1,2], legendrank=2))
 fig.add_trace(go.Bar(name="third", x=["a", "b"], y=[1,2], legendrank=3))
+fig.add_shape(
+    legendrank=1,
+    showlegend=True,
+    type="line",
+    xref="paper",
+    line=dict(dash="5px"),
+    x0=0.05,
+    x1=0.45,
+    y0=1.5,
+    y1=1.5,
+)
 fig.show()
 ```
 
 #### Showing and Hiding the Legend
 
-By default the legend is displayed on Plotly charts with multiple traces, and this can be explicitly set with the `layout.showlegend` attribute:
+By default the legend is displayed on Plotly charts with multiple traces, and this can be explicitly set with the `layout.showlegend` attribute.
 
 ```python
 import plotly.express as px
@@ -193,7 +233,7 @@ fig.show()
 
 *New in 5.11*
 
-Set the width of horizontal legend entries by setting `entrywidth`. Here we set it to `70` pixels. Pixels is the default unit for `entrywidth`, but you can set it to be a fraction of the plot width using `entrywidthmode='fraction`.
+Set the width of horizontal legend entries by setting `entrywidth`. Here we set it to `70` pixels. Pixels is the default unit for `entrywidth`, but you can set it to be a fraction of the plot width using `entrywidthmode='fraction'`.
 
 ```python
 import plotly.express as px
@@ -253,7 +293,30 @@ When creating figures using [graph objects](/python/graph-objects/) without usin
 
 #### Legend Item Names
 
-Legend items appear per trace, and the legend item name is taken from the trace's `name` attribute.
+For traces, legend items appear per trace, and the legend item name is taken from the trace's `name` attribute.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3, 4, 5],
+    y=[1, 2, 3, 4, 5],
+    name="Positive"
+))
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3, 4, 5],
+    y=[5, 4, 3, 2, 1],
+    name="Negative"
+))
+
+fig.show()
+```
+
+By default, for shapes, legend items are disabled. Set `showlegend=True` on a shape for it to display a legend item.
+The name that appears for the shape in the legend is the shape's `name` if it is provided. If no `name` is provided, the shape label's `text` is used. If neither is provided, the legend item appears as "shape \<shape number>". For example, "shape 1".
 
 ```python
 import plotly.graph_objects as go
@@ -272,6 +335,15 @@ fig.add_trace(go.Scatter(
     name="Negative"
 ))
 
+fig.add_shape(
+    showlegend=True,
+    type="rect",
+    x0=2,
+    x1=4,
+    y0=4.5,
+    y1=5,
+)
+
 fig.show()
 ```
 
@@ -324,7 +396,7 @@ fig.show()
 
 #### Hiding the Trace Initially
 
-Traces have a `visible` attribute. If set to `legendonly`, the trace is hidden from the graph implicitly. Click on the name in the legend to display the hidden trace.
+Traces and shapes have a `visible` attribute. If set to `legendonly`, the trace or shape is hidden from the graph implicitly. Click on the name in the legend to display the hidden trace or shape.
 
 ```python
 import plotly.graph_objects as go
@@ -578,7 +650,7 @@ fig.show()
 
 *New in 5.15*
 
-By default, all traces appear on one legend. To have multiple legends, specify an alternative legend for a trace using the `legend` property. For a second legend, set `legend="legend2"`. Specify more legends with `legend="legend3"`, `legend="legend4"` and so on.
+By default, all traces and shapes appear on one legend. To have multiple legends, specify an alternative legend for a trace or shape using the `legend` property. For a second legend, set `legend="legend2"`. Specify more legends with `legend="legend3"`, `legend="legend4"` and so on.
 
 In this example, the last two scatter traces display on the second legend, "legend2". On the figure's layout, we then position and style each legend.
 

Diff for: doc/python/px-arguments.md

@@ -170,14 +170,12 @@ fig.show()
 
 ### Input Data as Non-Pandas `DataFrame`s
 
-**New in 5.16**
+*New in 5.15*
 
-In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method or supports the [Python dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), for example, a [Polars](https://www.pola.rs/) DataFrame.
+In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method, for example, a [Polars](https://www.pola.rs/) DataFrame.
 
 Plotly Express uses Pandas internally to process the data. When you provide a Non-Pandas DataFrame to the `data_frame` argument of a Plotly Express function, the entire DataFrame is converted to a Pandas DataFrame.
 
-If you are using a type of DataFrame that doesn't have a `to_pandas` method, but supports the Python dataframe interchange protocol, you'll need to have Pandas version 2.0.3 or later installed. 
-
 In this example, we use a Polars DataFrame. If you are using Polars, you'll need to install `pyarrow`, which is used by its [`to_pandas` method](
 https://pola-rs.github.io/polars/py-polars/html/reference/dataframe/api/polars.DataFrame.to_pandas.html)
 
@@ -198,6 +196,13 @@ fig = px.bar(wide_df, x="nation", y=["gold", "silver", "bronze"], title="Wide-Fo
 fig.show()
 ```
 
+*New in 5.16*
+
+As of version 5.16, you can also provide another type of DataFrame to the `data_frame` argument if that DataFrame supports the [Python dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), or has a `toPandas` or `to_pandas_df` method.
+
+Even if the DataFrame that you are using supports the Python dataframe interchange protocol, you'll need to have Pandas version 2.0.3 or later installed. If you are using an earlier version of Pandas, Plotly Express will look for a `to_pandas`, `toPandas`, and `to_pandas_df` method, and use whichever one is available.
+
+
 ### Input Data as array-like columns: NumPy arrays, lists...
 
 `px` arguments can also be array-like objects such as lists, NumPy arrays, in both long-form or wide-form (for certain functions).

Diff for: doc/python/shapes.md

@@ -677,12 +677,12 @@ import plotly.graph_objects as go
 fig = go.Figure()
 
 fig.add_shape(
-    type="rect", 
-    fillcolor='turquoise', 
-    x0=1, 
-    y0=1, 
-    x1=2, 
-    y1=3, 
+    type="rect",
+    fillcolor='turquoise',
+    x0=1,
+    y0=1,
+    x1=2,
+    y1=3,
     label=dict(text="Text in rectangle")
 )
 fig.add_shape(
@@ -701,8 +701,8 @@ fig.show()
 
 #### Styling Text Labels
 
-Use the `font` property to configure the `color`, `size`, and `family` of the label font. 
-In this example, we change the label color of the first rectangle to "DarkOrange", set the size of the text above the line to 20, and change the font family and set the font size on the second rectangle. 
+Use the `font` property to configure the `color`, `size`, and `family` of the label font.
+In this example, we change the label color of the first rectangle to "DarkOrange", set the size of the text above the line to 20, and change the font family and set the font size on the second rectangle.
 
 ```python
 import plotly.graph_objects as go
@@ -776,7 +776,7 @@ fig.add_shape(
 
 fig.add_shape(
     type="line",
-    line_color="MediumSlateBlue",    
+    line_color="MediumSlateBlue",
     x0=3,
     y0=2,
     x1=5,
@@ -870,10 +870,10 @@ fig.show()
 
 #### Setting Label Anchors
 
-`xanchor` sets a label's horizontal positional anchor and `yanchor` sets its vertical position anchor. 
+`xanchor` sets a label's horizontal positional anchor and `yanchor` sets its vertical position anchor.
 Use `xanchor` to bind the `textposition` to the "left", "center" or "right" of the label text and `yanchor` to bind `textposition` to the "top", "middle" or "bottom" of the label text.
 
-In this example, `yanchor`is set to "top", instead of the default of "bottom" for lines, meaning the text displays below the line. 
+In this example, `yanchor`is set to "top", instead of the default of "bottom" for lines, meaning the text displays below the line.
 
 
 ```python
@@ -930,7 +930,7 @@ Use `texttemplate` to add text with variables to shapes. You have access to raw
 
 `texttemplate` supports d3 number and date formatting.
 
-Add a variable with "%{variable}". This example adds the raw variables `x0` and `y0` to a rectangle and shows the calculated variables `height`, `slope`, `length`, and `width` on three other shapes. 
+Add a variable with "%{variable}". This example adds the raw variables `x0` and `y0` to a rectangle and shows the calculated variables `height`, `slope`, `length`, and `width` on three other shapes.
 
 ```python
 import plotly.graph_objects as go
@@ -1017,6 +1017,85 @@ fig = go.Figure(
 )
 
 
+fig.show(
+    config={
+        "modeBarButtonsToAdd": [
+            "drawline",
+        ]
+    }
+)
+```
+
+#### Shapes in the Legend
+
+*New in 5.16*
+
+You can add a shape to the legend by setting `showlegend=True` on the shape. In this example, we add the second shape to the legend. The name that appears for the shape in the legend is the shape's `name` if it is provided. If no `name` is provided, the shape label's `text` is used. If neither is provided, the legend item appears as "shape \<shape number>". For example, "shape 1".
+
+```python
+import plotly.express as px
+
+df = px.data.stocks(indexed=True)
+
+fig = px.line(df)
+
+fig.add_shape(
+    type="rect",
+    x0="2018-09-24",
+    y0=0,
+    x1="2018-12-18",
+    y1=3,
+    line_width=0,
+    label=dict(text="Decline", textposition="top center", font=dict(size=20)),
+    fillcolor="green",
+    opacity=0.25,
+)
+
+fig.add_shape(
+    showlegend=True,
+    type="line",
+    x0=min(df.index),
+    y0=1,
+    x1=max(df.index),
+    y1=1,
+    line_width=3,
+    line_dash="dot",
+    label=dict(
+        text="Jan 1 2018 Baseline",
+        textposition="end",
+        font=dict(size=20, color="blue"),
+        yanchor="top",
+    ),
+)
+
+fig.show()
+```
+
+`newshape` also supports `showlegend`. In this example, each new line drawn on the graph appears in the legend.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.stocks()
+
+fig = go.Figure(
+    data=go.Scatter(
+        x=df.date,
+        y=df.AAPL,
+        name="Apple"
+    ),
+    layout=go.Layout(
+        yaxis=dict(title="Price in USD"),
+        newshape=dict(
+            showlegend=True,
+            label=dict(texttemplate="Change: %{dy:.2f}")
+        ),
+        title="Apple Share Price 2018/2019",
+    ),
+)
+
+
 fig.show(
     config={
         "modeBarButtonsToAdd": [