Merge branch 'doc-prod' into release_4.9.0

Author: nicolaskruchten

doc/python/2D-Histogram.md

@@ -96,7 +96,7 @@ fig.show()
 
 ### 2D Histograms with Graph Objects
 
-To build this kind of plot without using Plotly Express, we can use the `go.Histogram2d` class.
+To build this kind of figure using [graph objects](/python/graph-objects/) without using Plotly Express, we can use the `go.Histogram2d` class.
 
 
 ### 2D Histogram of a Bivariate Normal Distribution ###
@@ -236,4 +236,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/#histogram2d for more information and chart attribute options!
+See https://plotly.com/python/reference/#histogram2d for more information and chart attribute options!

doc/python/2d-histogram-contour.md

@@ -95,7 +95,7 @@ fig.show()
 
 ### 2D Histograms with Graph Objects
 
-To build this kind of plot without using Plotly Express, we can use the `go.Histogram2d` class.
+To build this kind of figure with [graph objects](/python/graph-objects/) without using Plotly Express, we can use the `go.Histogram2d` class.
 
 #### Basic 2D Histogram Contour
 
@@ -249,4 +249,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/#histogram2dcontour for more information and chart attribute options!
+See https://plotly.com/python/reference/#histogram2dcontour for more information and chart attribute options!

doc/python/animations.md

@@ -25,7 +25,7 @@ jupyter:
 
 #### Animated figures with Plotly Express
 
-Several Plotly Express functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
+Several [Plotly Express](/python/plotly-express/)  functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
 
 Here is an example of an animated scatter plot creating using Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation.
 
@@ -54,12 +54,12 @@ fig.show()
 ### Current Animation Limitations and Caveats
 
 * Animations are designed to work well when each row of input is present across all animation frames, and when categorical values mapped to symbol, color and facet are constant across frames. Animations *may be misleading or inconsistent* if these constraints are not met.
-* Although Plotly Express supports animation for many chart and map types, smooth inter-frame transitions are today only possible for scatter and bar
-* Plotly Express will not automatically compute the union of all x/y/color ranges, so these must be specified manually to avoid scale jumps across frames
+* Although Plotly Express supports animation for many chart and map types, smooth inter-frame transitions are today *only* possible for `scatter` and `bar`
+* Plotly Express will *not* automatically compute the union of all x/y/color ranges, so these must be specified manually to avoid scale jumps across frames
 
 #### Animated figures with Graph Objects
 
-The remainder of this section describes the low-level API for constructing animated figures manually.
+The remainder of this section describes the low-level [graph objects](/python/graph-objects/) API for constructing animated figures manually.
 
 #### Frames
 

doc/python/bubble-maps.md

@@ -35,7 +35,7 @@ jupyter:
 
 #### Base Map Configuration
 
-Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+Plotly figures made with [Plotly Express](/python/plotly-express/) `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` [graph objects](/python/graph-objects/) have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
 
 ### Bubble map with Plotly Express
 
@@ -208,4 +208,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#choropleth and https://plotly.com/python/reference/#scattergeo for more information and chart attribute options!
+See https://plotly.com/python/reference/#choropleth and https://plotly.com/python/reference/#scattergeo for more information and chart attribute options!

doc/python/choropleth-maps.md

@@ -39,7 +39,7 @@ Below we show how to create Choropleth Maps using either Plotly Express' `px.cho
 
 #### Base Map Configuration
 
-Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+Plotly figures made with [Plotly Express](/python/plotly-express/) `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` [graph objects](/python/graph-objects/) have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
 
 ### Introduction: main parameters for choropleth outline maps
 
@@ -347,4 +347,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#choropleth for more information and chart attribute options!
+See https://plotly.com/python/reference/#choropleth for more information and chart attribute options!

doc/python/colorscales.md

@@ -52,7 +52,7 @@ This document explains the following four continuous-color-related concepts:
 
 ### Continuous Color with Plotly Express
 
-Most Plotly Express functions accept a `color` argument which automatically assigns data values to continuous color **if the data is numeric**. If the data contains strings, the color will automatically be considered [discrete (also known as categorical or qualitative)](/python/discrete-color/). This means that numeric strings must be parsed to be used for continuous color, and conversely, numbers used as category codes must be converted to strings.
+Most [Plotly Express](/python/plotly-express/) functions accept a `color` argument which automatically assigns data values to continuous color **if the data is numeric**. If the data contains strings, the color will automatically be considered [discrete (also known as categorical or qualitative)](/python/discrete-color/). This means that numeric strings must be parsed to be used for continuous color, and conversely, numbers used as category codes must be converted to strings.
 
 For example, in the `tips` dataset, the `size` column contains numbers:
 
@@ -92,7 +92,7 @@ fig.show()
 
 ### Color Scales in Plotly Express
 
-By default, Plotly Express will use the color scale from the active [template](/python/templates/)'s `layout.colorscales.sequential` attribute, and the default active template is `plotly` which uses the `Plasma` color scale. You can choose any of the [built-in color scales](/python/builtin-colorscales/), however, or define your own.
+By default, [Plotly Express](/python/plotly-express/) will use the color scale from the active [template](/python/templates/)'s `layout.colorscales.sequential` attribute, and the default active template is `plotly` which uses the `Plasma` color scale. You can choose any of the [built-in color scales](/python/builtin-colorscales/), however, or define your own.
 
 Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis color scale.
 
@@ -557,4 +557,4 @@ fig.show()
 
 ### Reference
 
-See https://plotly.com/python/reference/ for more information and chart attribute options!
+See https://plotly.com/python/reference/ for more information and chart attribute options!

doc/python/figure-labels.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.1
+      format_version: '1.2'
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
   plotly:
     description: How to set the global font, title, legend-entries, and axis-titles
       in python.
@@ -34,6 +34,62 @@ jupyter:
     thumbnail: thumbnail/figure-labels.png
 ---
 
+### Automatic Labelling with Plotly Express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
+
+When using Plotly Express, your axes and legend are automatically labelled, and it's easy to override the automation for a customized figure using the `labels` keyword argument. The title of your figure is up to you though!
+
+Here's a figure with automatic labels and then the same figure with overridden labels. Note the fact that when overriding labels, the axes, legend title *and hover labels* reflect the specified labels automatically.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
+                title="Automatic Labels Based on Data Frame Column Names")
+fig.show()
+```
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
+                 labels={
+                     "sepal_length": "Sepal Length (cm)",
+                     "sepal_width": "Sepal Width (cm)",
+                     "species": "Species of Iris"
+                 },
+                title="Manually Specified Labels")
+fig.show()
+```
+
+### Global and Local Font Specification
+
+You can set the figure-wide font with the `layout.font` attribute, which will apply to all titles and tick labels, but this can be overridden for specific plot items like individual axes and legend titles etc. In the following figure, we set the figure-wide font to Courier New in blue, and then override this for certain parts of the figure.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
+                title="Playing with Fonts")
+fig.update_layout(
+    font_family="Courier New",
+    font_color="blue",
+    title_font_family="Times New Roman",
+    title_font_color="red",
+    legend_title_font_color="green"
+)
+fig.update_xaxes(title_font_family="Arial")
+fig.show()
+```
+
+### Manual Labelling with Graph Objects
+
+When using (graph objects)[/python/graph-objects/] rather than [Plotly Express](/python/plotly-express/), you will need to explicitly label traces and axes:
+
 ```python
 import plotly.graph_objects as go
 
@@ -54,12 +110,13 @@ fig.add_trace(go.Scatter(
 
 fig.update_layout(
     title="Plot Title",
-    xaxis_title="x Axis Title",
-    yaxis_title="y Axis Title",
+    xaxis_title="X Axis Title",
+    yaxis_title="X Axis Title",
+    legend_title="Legend Title",
     font=dict(
         family="Courier New, monospace",
         size=18,
-        color="#7f7f7f"
+        color="RebeccaPurple"
     )
 )
 
@@ -90,4 +147,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/#layout for more information!
+See https://plotly.com/python/reference/#layout for more information!

doc/python/figure-structure.md

@@ -101,9 +101,9 @@ At [render-time](/python/renderers/), it is also possible to control certain fig
 
 Various figure components configured within the layout of the figure support positioning attributes named `x` or `y`, whose values may be specified in "paper coordinates" (sometimes referred to as "plot fractions" or "normalized coordinates"). Examples include `layout.xaxis.domain` or `layout.legend.x` or `layout.annotation[].x`.
 
-Positioning in paper coordinates is not done in absolute pixel terms, but rather in terms relative to a coordinate system defined with an origin `(0,0)` at `(layout.margin.l, layout.margin.b)` and a point `(1,1)` at `(layout.width-layout.margin.r, layout.height-layout.margin.t)`. Values less than 0 or greater than 1 are permitted, and refer to areas within the plot margins.
+Positioning in paper coordinates is *not* done in absolute pixel terms, but rather in terms relative to a coordinate system defined with an origin `(0,0)` at `(layout.margin.l, layout.margin.b)` and a point `(1,1)` at `(layout.width-layout.margin.r, layout.height-layout.margin.t)` (note: `layout.margin` values are pixel values, as are `layout.width` and `layout.height`). Paper coordinate values less than 0 or greater than 1 are permitted, and refer to areas within the plot margins.
 
-Note that the contents of the `layout.margin` attribute are by default computed based on the position and dimensions of certain items like the title or legend, and may be made dependent on the position and dimensions of tick labels as well when setting the `layout.xaxis.automargin` attribute to `True`. This has the effect of automatically increasing the margin values and therefore shrinking the physical area defined between the `(0,0)` and `(1,1)` points. Positioning certain items at paper coordinates less than 0 or greater than 1 will also trigger this behavior.
+Note that the contents of the `layout.margin` attribute are by default computed based on the position and dimensions of certain items like the title or legend, and may be made dependent on the position and dimensions of tick labels as well when setting the `layout.xaxis.automargin` attribute to `True`. This has the effect of automatically increasing the margin values and therefore shrinking the physical area defined between the `(0,0)` and `(1,1)` points. Positioning certain items at paper coordinates less than 0 or greater than 1 will also trigger this behavior. The `layout.width` and `layout.height`, however, are taken as givens, so a figure will never grow or shrink based on its contents.
 
 The figure title may be positioned using "container coordinates" which have `(0,0)` and `(1,1)` anchored at the bottom-left and top-right of the figure, respectively, and therefore are independent of the values of layout.margin.
 
@@ -184,8 +184,12 @@ The following trace types are compatible with `carpet` trace subplots via the `c
 
 ### Trace Types, Legends and Color Bars
 
-Traces of most types can be optionally associated with a single legend item in the [legend](/python/legend/), which can be shown 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 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.
 
 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.
 
-Traces which support [continuous color](/python/colorscales/) can also be associated with color axes in the layout via the `coloraxis` attribute. Multiple traces can be linked to the same color axis. Color axes have a legend-like component called color bars. Alternatively, color axes can be configured within the trace itself.
+Traces which support [continuous color](/python/colorscales/) can also be associated with color axes in the layout via the `coloraxis` attribute. Multiple traces can be linked to the same color axis. Color axes have a legend-like component called color bars. Alternatively, color axes can be configured within the trace itself.
+
+```python
+
+```