Merge pull request #2075 from plotly/doc-prod

Doc prod merge

Author: nicolaskruchten

.circleci/config.yml

@@ -381,7 +381,7 @@ jobs:
     steps:
       - add_ssh_keys:
           fingerprints:
-            - "3e:4b:19:1c:c2:d1:92:dd:bf:f8:c9:d6:a6:78:69:2a"
+            - "dc:5f:39:48:00:b4:72:34:e1:d2:c4:e1:1f:d1:e2:ce" #plotlydocbot
 
       - checkout
 
@@ -431,10 +431,10 @@ jobs:
             if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then
               cd build/html
               git init
-              git config user.name nicolaskruchten
-              git config user.email nicolas@plot.ly
+              git config user.name plotlydocbot
+              git config user.email accounts@plot.ly
               git add *
-              git commit -m build
+              git commit -m "build of https://github.com/plotly/plotly.py/commit/${CIRCLE_SHA1}"
               git push --force [email protected]:plotly/plotly.py-docs.git master:built
               rm -rf .git
               cd ../..
@@ -443,6 +443,20 @@ jobs:
             rm -rf build/html build/ipynb
             cd ..
 
+      - run:
+          name: trigger doc build
+          command: |
+            if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then
+              git clone --depth=1 --branch=source-design-merge https://github.com/plotly/documentation.git
+              cd documentation
+              git config user.name plotlydocbot
+              git config user.email [email protected]
+              git commit --allow-empty -m "deploying https://github.com/plotly/plotly.py/commit/${CIRCLE_SHA1}"
+              git push
+              cd ..
+              rm -rf documentation
+            fi
+
       - run:
           name: make doc
           command: |
@@ -454,11 +468,11 @@ jobs:
               cd _build/html
               touch .nojekyll
               git init
-              git config user.name emmanuelle
-              git config user.email emma@plot.ly
+              git config user.name plotlydocbot
+              git config user.email accounts@plot.ly
               git add *
               git add .nojekyll
-              git commit -m build
+              git commit -m "build of https://github.com/plotly/plotly.py/commit/${CIRCLE_SHA1}"
               git push --force [email protected]:plotly/plotly.py-docs.git master:gh-pages
               rm -rf .git
               cd ../..

doc/python/3d-mesh.md

@@ -103,6 +103,8 @@ fig.show()
 
 ```python
 import plotly.graph_objects as go
+import numpy as np
+
 fig = go.Figure(data=[
     go.Mesh3d(
         # 8 vertices of a cube

doc/python/axes.md

@@ -622,6 +622,37 @@ fig.update_layout(
 fig.show()
 ```
 
+### Fixed Ratio Axes with Compressed domain
+
+If an axis needs to be compressed (either due to its own `scaleanchor` and `scaleratio` or those of the other axis), `constrain` determines how that happens: by increasing the "range" (default), or by decreasing the "domain".
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Scatter(
+    x = [0,1,1,0,0,1,1,2,2,3,3,2,2,3],
+    y = [0,0,1,1,3,3,2,2,3,3,1,1,0,0]
+))
+
+fig.update_layout(
+    width = 800,
+    height = 500,
+    title = "fixed-ratio axes with compressed axes",
+    xaxis = dict(
+      range=[-1,4],  # sets the range of xaxis
+      constrain="domain",  # meanwhile compresses the xaxis by decreasing its "domain"
+    ),
+    yaxis = dict(
+      scaleanchor = "x",
+      scaleratio = 1,
+    ),
+)
+
+fig.show()
+```
+
 #### Reversed Axes
 
 You can tell plotly's automatic axis range calculation logic to reverse the direction of an axis by setting the `autorange` axis property to `"reversed"`.
@@ -682,7 +713,7 @@ fig.show()
 
 The axis auto-range calculation logic can be configured using the `rangemode` axis parameter.
 
-If `rangemode` is `"normal"` (the default), the range is computed based on the min and max values of the input data. If `"tozero"`, the the range will always include zero. If `"nonnegative"`, the range will not extend below zero, regardless of the input data.
+If `rangemode` is `"normal"` (the default), the range is computed based on the min and max values of the input data. If `"tozero"`, the range will always include zero. If `"nonnegative"`, the range will not extend below zero, regardless of the input data.
 
 Here is an example of configuring a faceted scatter plot created using Plotly Express to always include zero for both the x and y axes.
 

doc/python/builtin-colorscales.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
+      format_version: "1.2"
       jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
@@ -22,34 +22,39 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.8
   plotly:
-    description: A reference for the built-in named continuous (sequential, diverging
-      and cylclical) colorscales in Plotly.
+    description:
+      A reference for the built-in named continuous (sequential, diverging
+      and cylclical) color scales in Plotly.
     display_as: file_settings
     has_thumbnail: true
     ipynb: ~notebook_demo/187
     language: python
     layout: base
-    name: Built-in Continuous Colorscales
+    name: Built-in Continuous Color Scales
     order: 27
     permalink: python/builtin-colorscales/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true
 ---
 
-### Using Built-In Colorscales
+### Using Built-In Continuous Color Scales
 
 Many Plotly Express functions accept a `color_continuous_scale` argument and many trace
 types have a `colorscale` attribute in their schema. Plotly comes with a large number of
-built-in continuous colorscales, which can be referred to in Python code when setting the above arguments,
+built-in continuous color scales, which can be referred to in Python code when setting the above arguments,
 either by name in a case-insensitive string e.g. `px.scatter(continuous_color_scale="Viridis"`) or by reference e.g.
 `go.Scatter(marker_colorscale=plotly.colors.sequential.Viridis)`. They can also be reversed by adding `_r` at the end
 e.g. `"Viridis_r"` or `plotly.colors.sequential.Viridis_r`.
 
 The `plotly.colours` module is also available under `plotly.express.colors` so you can refer to it as `px.colors`.
 
-When using continuous colorscales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
+When using continuous color scales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
 
-### Named Built-In Colorscales
+### Discrete Color Sequences
+
+Plotly also comes with some built-in [discrete color sequences](/python/discrete-color/) which are _not intended_ to be used with the `color_continuous_scale` argument as they are not designed for interpolation to occur between adjacent colors.
+
+### Named Built-In Continuous Color Scales
 
 You can use any of the following names as string values to set `continuous_color_scale` or `colorscale` arguments.
 These strings are case-insensitive and you can append `_r` to them to reverse the order of the scale.
@@ -62,7 +67,15 @@ named_colorscales = px.colors.named_colorscales()
 print("\n".join(wrap("".join('{:<12}'.format(c) for c in named_colorscales), 96)))
 ```
 
-### Built-In Sequential Colorscales
+Built-in color scales are stored as lists of CSS colors:
+
+```python
+import plotly.express as px
+
+print(px.colors.sequential.Plasma)
+```
+
+### Built-In Sequential Color scales
 
 A collection of predefined sequential colorscales is provided in the `plotly.colors.sequential` module. Sequential color scales are appropriate for most continuous data, but in some cases it can be helpful to use a diverging or cyclical color scale (see below).
 
@@ -78,12 +91,12 @@ fig.show()
 Note: `RdBu` was included in this module by mistake, even though it is a diverging color scale.
 It is intentionally left in for backwards-compatibility reasons.
 
-### Built-In Diverging Colorscales
+### Built-In Diverging Color scales
 
-A collection of predefined diverging colorscales is provided in the `plotly.colors.diverging` module.
+A collection of predefined diverging color scales is provided in the `plotly.colors.diverging` module.
 Diverging color scales are appropriate for continuous data that has a natural midpoint
 other otherwise informative special value, such as 0 altitude, or the boiling point
-of a liquid. These scales are intended to be used when [explicitly setting the midpoint of the scale](/python/colorscales/#setting-the-midpoint-of-a-diverging-colorscale).
+of a liquid. These scales are intended to be used when [explicitly setting the midpoint of the scale](/python/colorscales/#setting-the-midpoint-of-a-color-range-for-a-diverging-color-scale).
 
 Here are all the built-in scales in the `plotly.colors.diverging` module:
 
@@ -94,9 +107,9 @@ fig = px.colors.diverging.swatches()
 fig.show()
 ```
 
-### Built-In Cyclical Colorscales
+### Built-In Cyclical Color scales
 
-A collection of predefined cyclical colorscales is provided in the `plotly.colors.cyclical` module.
+A collection of predefined cyclical color scales is provided in the `plotly.colors.cyclical` module.
 Cyclical color scales are appropriate for continuous data that has a natural cyclical
 structure, such as temporal data (hour of day, day of week, day of year, seasons) or
 complex numbers or other phase or angular data.