Merge pull request #3931 from plotly/docs-oct

Documentation updates for 5.11

doc/python/dumbbell-plots.md

@@ -0,0 +1,176 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.3'
+      jupytext_version: 1.14.1
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.8.0
+  plotly:
+    description: How to create dumbbell plots in Python with Plotly.
+    display_as: basic
+    language: python
+    layout: base
+    name: Dumbbell Plots
+    order: 19
+    page_type: example_index
+    permalink: python/dumbbell-plots/
+    thumbnail: thumbnail/dumbbell-plot.jpg
+---
+
+## Basic Dumbbell Plot
+
+
+Dumbbell plots are useful for demonstrating change between two sets of data points, for example, the population change for a selection of countries for two different years
+
+In this example, we compare life expectancy in 1952 with life expectancy in 2002 for countries in Europe.
+
+```python
+import plotly.graph_objects as go
+from plotly import data
+
+import pandas as pd
+
+df = data.gapminder()
+df = df.loc[(df.continent == "Europe") & (df.year.isin([1952, 2002]))]
+
+countries = (
+    df.loc[(df.continent == "Europe") & (df.year.isin([2002]))]
+    .sort_values(by=["lifeExp"], ascending=True)["country"]
+    .unique()
+)
+
+data = {"x": [], "y": [], "colors": [], "years": []}
+
+for country in countries:
+    data["x"].extend(
+        [
+            df.loc[(df.year == 1952) & (df.country == country)]["lifeExp"].values[0],
+            df.loc[(df.year == 2002) & (df.country == country)]["lifeExp"].values[0],
+            None,
+        ]
+    )
+    data["y"].extend([country, country, None]),
+    data["colors"].extend(["green", "blue", "brown"]),
+    data["years"].extend(["1952", "2002", None])
+
+fig = go.Figure(
+    data=[
+        go.Scatter(
+            x=data["x"],
+            y=data["y"],
+            mode="lines",
+            marker=dict(
+                color="grey",
+            ),
+        ),
+        go.Scatter(
+            x=data["x"],
+            y=data["y"],
+            mode="markers+text",
+            marker=dict(
+                color=data["colors"],
+                size=10,
+            ),
+            hovertemplate="""Country: %{y} <br> Life Expectancy: %{x} <br><extra></extra>""",
+        ),
+    ]
+)
+
+fig.update_layout(
+    title="Life Expectancy in Europe: 1952 and 2002",
+    width=1000,
+    height=1000,
+    showlegend=False,
+)
+
+fig.show()
+
+```
+
+## Dumbbell Plot with Arrow Markers
+
+*Note: The `arrow`, `angleref`, and `standoff` properties used on the `marker` in this example are new in 5.11*
+
+In this example, we add arrow markers to the plot. The first trace adds the lines connecting the data points and arrow markers. 
+The second trace adds circle markers. On the first trace, we use `standoff=8` to position the arrow marker back from the data point.
+For the arrow marker to point directly at the circle marker, this value should be half the circle marker size. 
+
+```python
+import pandas as pd
+import plotly.graph_objects as go
+from plotly import data
+
+df = data.gapminder()
+df = df.loc[(df.continent == "Europe") & (df.year.isin([1952, 2002]))]
+
+countries = (
+    df.loc[(df.continent == "Europe") & (df.year.isin([2002]))]
+    .sort_values(by=["lifeExp"], ascending=True)["country"]
+    .unique()
+)
+
+data = {"x": [], "y": [], "colors": [], "years": []}
+
+for country in countries:
+    data["x"].extend(
+        [
+            df.loc[(df.year == 1952) & (df.country == country)]["lifeExp"].values[0],
+            df.loc[(df.year == 2002) & (df.country == country)]["lifeExp"].values[0],
+            None,
+        ]
+    )
+    data["y"].extend([country, country, None]),
+    data["colors"].extend(["silver", "lightskyblue", "white"]),
+    data["years"].extend(["1952", "2002", None])
+
+fig = go.Figure(
+    data=[
+        go.Scatter(
+            x=data["x"],
+            y=data["y"],
+            mode="markers+lines",
+            marker=dict(
+                symbol="arrow", color="black", size=16, angleref="previous", standoff=8
+            ),
+        ),
+        go.Scatter(
+            x=data["x"],
+            y=data["y"],
+            text=data["years"],
+            mode="markers",
+            marker=dict(
+                color=data["colors"],
+                size=16,
+            ),
+            hovertemplate="""Country: %{y} <br> Life Expectancy: %{x} <br> Year: %{text} <br><extra></extra>""",
+        ),
+    ]
+)
+
+fig.update_layout(
+    title="Life Expectancy in Europe: 1952 and 2002",
+    width=1000,
+    height=1000,
+    showlegend=False,
+)
+
+
+fig.show()
+
+```

doc/python/legend.md

@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.3'
       jupytext_version: 1.14.1
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.8.8
+    version: 3.8.0
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -189,6 +189,31 @@ fig.update_layout(legend=dict(
 fig.show()
 ```
 
+#### Horizontal Legend Entry Width
+
+*New in 5.11*
+
+Set the width of hozitonal 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
+
+df = px.data.gapminder().query("year==2007")
+fig = px.scatter(df, x="gdpPercap", y="lifeExp", color="continent",
+    size="pop", size_max=45, log_x=True)
+
+fig.update_layout(legend=dict(
+    orientation="h",
+    entrywidth=70,
+    yanchor="bottom",
+    y=1.02,
+    xanchor="right",
+    x=1
+))
+
+fig.show()
+```
+
 #### Styling Legends
 
 Legends support many styling options.

doc/python/mapbox-layers.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.3.1
+      format_version: '1.3'
+      jupytext_version: 1.14.1
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.8.0
   plotly:
     description: How to make Mapbox maps in Python with various base layers, with
       or without needing a Mapbox Access token.
@@ -192,6 +192,37 @@ fig.show()
 
 See the example in the [plotly and datashader tutorial](/python/datashader).
 
+
+#### Setting Map Bounds
+
+*New in 5.11*
+
+Set bounds for a map to specify an area outside which a user interacting with the map can't pan or zoom. Here we set a maximum longitude of `-180`, a minimum longitude of `-50`, a maximum latitude of `90`, and a minimum latitude of `20`.
+
+```python
+import plotly.express as px
+import pandas as pd
+
+us_cities = pd.read_csv(
+    "https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv"
+)
+
+fig = px.scatter_mapbox(
+    us_cities,
+    lat="lat",
+    lon="lon",
+    hover_name="City",
+    hover_data=["State", "Population"],
+    color_discrete_sequence=["fuchsia"],
+    zoom=3,
+    height=300,
+)
+fig.update_layout(mapbox_style="open-street-map")
+fig.update_layout(margin={"r": 0, "t": 0, "l": 0, "b": 0})
+fig.update_layout(mapbox_bounds={"west": -180, "east": -50, "south": 20, "north": 90})
+fig.show()
+```
+
 #### Reference
 
 See https://plotly.com/python/reference/layout/mapbox/ for more information and options!