Merge pull request #5235 from plotly/merge-doc-prod-changes-to-main

Merge recent doc prod changes to main

Author: LiamConnors

doc/python/dropdowns.md

@@ -365,27 +365,27 @@ fig.add_trace(
     go.Scatter(x=list(df.Date),
                y=list(df.High),
                name="High",
-               line=dict(color="#33CFA5")))
+               line=dict(color="DarkBlue")))
 
 fig.add_trace(
     go.Scatter(x=list(df.Date),
                y=[df.High.mean()] * len(df.index),
                name="High Average",
                visible=False,
-               line=dict(color="#33CFA5", dash="dash")))
+               line=dict(color="DarkBlue", dash="dash")))
 
 fig.add_trace(
     go.Scatter(x=list(df.Date),
                y=list(df.Low),
                name="Low",
-               line=dict(color="#F06A6A")))
+               line=dict(color="Crimson")))
 
 fig.add_trace(
     go.Scatter(x=list(df.Date),
                y=[df.Low.mean()] * len(df.index),
                name="Low Average",
                visible=False,
-               line=dict(color="#F06A6A", dash="dash")))
+               line=dict(color="Crimson", dash="dash")))
 
 # Add Annotations and Buttons
 high_annotations = [dict(x="2016-03-01",

doc/python/facet-plots.md

@@ -54,6 +54,8 @@ fig.show()
 
 ### Bar Chart Row Facets
 
+There is a more presentation-ready horizontal, faceted bar chart in the [horizontal bar documentation](/python/horizontal-bar-charts/#Small-multiple-horizontal-bar-charts-show-each-component's-size-more-clearly-than-a-stacked-bar)
+
 ```python
 import plotly.express as px
 df = px.data.tips()

doc/python/graph-objects.md

@@ -68,7 +68,9 @@ Note that the figures produced by Plotly Express **in a single function-call** a
 
 The figures produced by Plotly Express can always be built from the ground up using graph objects, but this approach typically takes **5-100 lines of code rather than 1**. 
 
-Here is a simple example of how to produce the same figure object from the same data, once with Plotly Express and once without. The data in this example is in "long form" but [Plotly Express also accepts data in "wide form"](/python/wide-form/) and the line-count savings from Plotly Express over graph objects are comparable. More complex figures such as [sunbursts](/python/sunburst-charts/), [parallel coordinates](/python/parallel-coordinates-plot/), [facet plots](/python/facet-plots/) or [animations](/python/animations/) require many more lines of figure-specific graph objects code, whereas switching from one representation to another with Plotly Express usually involves changing just a few characters.
+Here is a simple example of how to produce the same figure object from the same data, once with Plotly Express and once without. Note that [Plotly Express functions](/python-api-reference/plotly.express.html) like [`px.bar()`](/python/bar-charts/) can accept a DataFrame as their first argument with column names passed to the `x` and `y` arguments, while [Graph Objects functions](/python-api-reference/plotly.graph_objects.html) like [`go.Bar()`](/python/bar-charts/#basic-bar-charts-with-plotlygraphobjects) require the data values to be passed directly to the `x` and `y` arguments as a tuple, list, NumPy array, or Pandas Series.
+
+The data in this example is in "long form" but [Plotly Express also accepts data in "wide form"](/python/wide-form/) and the line-count savings from Plotly Express over graph objects are comparable. More complex figures such as [sunbursts](/python/sunburst-charts/), [parallel coordinates](/python/parallel-coordinates-plot/), [facet plots](/python/facet-plots/) or [animations](/python/animations/) require many more lines of figure-specific graph objects code, whereas switching from one representation to another with Plotly Express usually involves changing just a few characters.
 
 ```python
 import pandas as pd

doc/python/horizontal-bar-charts.md

@@ -91,8 +91,8 @@ fig.add_trace(go.Bar(
     name='SF Zoo',
     orientation='h',
     marker=dict(
-        color='rgba(246, 78, 139, 0.6)',
-        line=dict(color='rgba(246, 78, 139, 1.0)', width=3)
+        color='hotpink',
+        line=dict(color='deeppink', width=3)
     )
 ))
 fig.add_trace(go.Bar(
@@ -101,27 +101,69 @@ fig.add_trace(go.Bar(
     name='LA Zoo',
     orientation='h',
     marker=dict(
-        color='rgba(58, 71, 80, 0.6)',
-        line=dict(color='rgba(58, 71, 80, 1.0)', width=3)
+        color='dimgray',
+        line=dict(color='black', width=3)
     )
 ))
 
 fig.update_layout(barmode='stack')
+fig.show()
+```
+### Small multiple horizontal bar charts show each component's size more clearly than a stacked bar
+
+Bar charts with multiple components pose a fundamental trade off between presenting the total clearly and presenting the component values clearly. This small multiples approach shows the component magnitudes clearly at the cost of slightly obscuring the totals. A stacked bar does the opposite. Small multiple bar charts often work better in a horizontal orientation; and are easy to create with the px.bar orientation and facet_col parameters.
+```python
+import pandas as pd
+import plotly.express as px
+
+data = {
+    "Quarter": ["Q1", "Q2", "Q3", "Q4"] * 3,
+    "Region": ["North", "North", "North", "North", "South", "South", "South", "South", "West", "West", "West", "West"],
+    "Outcome": [150, 200, 250, 300, 120, 180, 240, 310, 100, 150, 220, 280]
+}
+df = pd.DataFrame(data)
+
+
+fig = px.bar(
+    df, 
+    x="Outcome", 
+    y="Region",
+    orientation="h",  
+    facet_col="Quarter", 
+    title="Number of Patients Served by Region and Quarter", 
+    labels={"Outcome": "Patients Served", "Region": "Region"} 
+)
+
+## the section below is optional clean up to make this presentation ready
+
+fig.update_layout(
+    height=400,  #the Plotly default makes the bars awkwardly large; setting a height improves the display
+    showlegend=False,  # the legend does not add anything
+)
+
+# remove the default "facet_variable =" text from the title of each facet graph
+fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1]))  
+
+# Remove duplicate axis labels
+fig.for_each_yaxis(lambda axis: axis.update(title=None))
+fig.for_each_xaxis(lambda axis: axis.update(title=None))
+# add the one valuable axis label back in
+fig.update_xaxes(title="Count", row=1, col=1)
+
 fig.show()
 ```
 
 ### Color Palette for Bar Chart
 
+This bar chart uses a sequential palette to show gradations of responses.  Additional color options for sequential palettes are available at [The Urban Institute](https://urbaninstitute.github.io/graphics-styleguide/#color) and [Colorbrewer](https://colorbrewer2.org/#type=sequential)
+
 ```python
 import plotly.graph_objects as go
 
 top_labels = ['Strongly<br>agree', 'Agree', 'Neutral', 'Disagree',
               'Strongly<br>disagree']
 
-colors = ['rgba(38, 24, 74, 0.8)', 'rgba(71, 58, 131, 0.8)',
-          'rgba(122, 120, 168, 0.8)', 'rgba(164, 163, 204, 0.85)',
-          'rgba(190, 192, 213, 1)']
-
+colors = ['DarkBlue', 'MediumBlue', 'DarkSlateBlue', 'mediumpurple', 'thistle']
 x_data = [[21, 30, 21, 16, 12],
           [24, 31, 19, 15, 11],
           [27, 26, 23, 11, 13],
@@ -142,7 +184,7 @@ for i in range(0, len(x_data[0])):
             orientation='h',
             marker=dict(
                 color=colors[i],
-                line=dict(color='rgb(248, 248, 249)', width=1)
+                line=dict(color='ghostwhite', width=1)
             )
         ))
 
@@ -161,8 +203,8 @@ fig.update_layout(
         zeroline=False,
     ),
     barmode='stack',
-    paper_bgcolor='rgb(248, 248, 255)',
-    plot_bgcolor='rgb(248, 248, 255)',
+    paper_bgcolor='lavenderblush',
+    plot_bgcolor='lavenderblush',
     margin=dict(l=120, r=10, t=140, b=80),
     showlegend=False,
 )
@@ -176,22 +218,22 @@ for yd, xd in zip(y_data, x_data):
                             xanchor='right',
                             text=str(yd),
                             font=dict(family='Arial', size=14,
-                                      color='rgb(67, 67, 67)'),
+                                      color='dimgray'),
                             showarrow=False, align='right'))
     # labeling the first percentage of each bar (x_axis)
     annotations.append(dict(xref='x', yref='y',
                             x=xd[0] / 2, y=yd,
                             text=str(xd[0]) + '%',
                             font=dict(family='Arial', size=14,
-                                      color='rgb(248, 248, 255)'),
+                                      color='white'),
                             showarrow=False))
     # labeling the first Likert scale (on the top)
     if yd == y_data[-1]:
         annotations.append(dict(xref='x', yref='paper',
                                 x=xd[0] / 2, y=1.1,
                                 text=top_labels[0],
                                 font=dict(family='Arial', size=14,
-                                          color='rgb(67, 67, 67)'),
+                                          color='dimgray'),
                                 showarrow=False))
     space = xd[0]
     for i in range(1, len(xd)):
@@ -200,15 +242,15 @@ for yd, xd in zip(y_data, x_data):
                                     x=space + (xd[i]/2), y=yd,
                                     text=str(xd[i]) + '%',
                                     font=dict(family='Arial', size=14,
-                                              color='rgb(248, 248, 255)'),
+                                              color='ghostwhite'),
                                     showarrow=False))
             # labeling the Likert scale
             if yd == y_data[-1]:
                 annotations.append(dict(xref='x', yref='paper',
                                         x=space + (xd[i]/2), y=1.1,
                                         text=top_labels[i],
                                         font=dict(family='Arial', size=14,
-                                                  color='rgb(67, 67, 67)'),
+                                                  color='dimgray'),
                                         showarrow=False))
             space += xd[i]
 
@@ -313,9 +355,9 @@ fig.add_trace(go.Bar(
     x=y_saving,
     y=x,
     marker=dict(
-        color='rgba(50, 171, 96, 0.6)',
+        color='mediumseagreen',
         line=dict(
-            color='rgba(50, 171, 96, 1.0)',
+            color='seagreen',
             width=1),
     ),
     name='Household savings, percentage of household disposable income',
@@ -325,7 +367,7 @@ fig.add_trace(go.Bar(
 fig.add_trace(go.Scatter(
     x=y_net_worth, y=x,
     mode='lines+markers',
-    line_color='rgb(128, 0, 128)',
+    line_color='purple',
     name='Household net worth, Million USD/capita',
 ), 1, 2)
 
@@ -341,7 +383,7 @@ fig.update_layout(
         showgrid=False,
         showline=True,
         showticklabels=False,
-        linecolor='rgba(102, 102, 102, 0.8)',
+        linecolor='gray',
         linewidth=2,
         domain=[0, 0.85],
     ),
@@ -363,8 +405,8 @@ fig.update_layout(
     ),
     legend=dict(x=0.029, y=1.038, font_size=10),
     margin=dict(l=100, r=20, t=70, b=70),
-    paper_bgcolor='rgb(248, 248, 255)',
-    plot_bgcolor='rgb(248, 248, 255)',
+    paper_bgcolor='lavenderblush',
+    plot_bgcolor='lavenderblush',
 )
 
 annotations = []
@@ -379,14 +421,14 @@ for ydn, yd, xd in zip(y_nw, y_s, x):
                             y=xd, x=ydn - 20000,
                             text='{:,}'.format(ydn) + 'M',
                             font=dict(family='Arial', size=12,
-                                      color='rgb(128, 0, 128)'),
+                                      color='purple'),
                             showarrow=False))
     # labeling the bar net worth
     annotations.append(dict(xref='x1', yref='y1',
                             y=xd, x=yd + 3,
                             text=str(yd) + '%',
-                            font=dict(family='Arial', size=12,
-                                      color='rgb(50, 171, 96)'),
+                            font=dict(family='Arial', size=16,
+                                      color='mediumseagreen'),
                             showarrow=False))
 # Source
 annotations.append(dict(xref='paper', yref='paper',
@@ -395,7 +437,7 @@ annotations.append(dict(xref='paper', yref='paper',
                              '(2015), Household savings (indicator), ' +
                              'Household net worth (indicator). doi: ' +
                              '10.1787/cfc6f499-en (Accessed on 05 June 2015)',
-                        font=dict(family='Arial', size=10, color='rgb(150,150,150)'),
+                        font=dict(family='Arial', size=10, color='gray'),
                         showarrow=False))
 
 fig.update_layout(annotations=annotations)

plotly/express/_doc.py

@@ -612,7 +612,12 @@
 def make_docstring(fn, override_dict=None, append_dict=None):
     override_dict = {} if override_dict is None else override_dict
     append_dict = {} if append_dict is None else append_dict
-    tw = TextWrapper(width=75, initial_indent="    ", subsequent_indent="    ")
+    tw = TextWrapper(
+        width=75,
+        initial_indent="    ",
+        subsequent_indent="    ",
+        break_on_hyphens=False,
+    )
     result = (fn.__doc__ or "") + "\nParameters\n----------\n"
     for param in getfullargspec(fn)[0]:
         if override_dict.get(param):