merge doc-prod to master

Author: nicolaskruchten

.circleci/config.yml

@@ -400,6 +400,7 @@ jobs:
             . venv/bin/activate
             npm install electron@1.8.4
             npm install orca
+            pip uninstall -y plotly
             pip install -r requirements.txt
             if [ "${CIRCLE_BRANCH}" != "doc-prod" ]; then
               pip uninstall -y plotly

doc/README.md

@@ -2,15 +2,15 @@
 
 ## Introduction: structure and required packages
 
-The `doc` directory contains the source files of the documentation of plotly.py. 
+The `doc` directory contains the source files of the documentation of plotly.py.
 It is composed of two parts:
 
 - inside the [`python/` directory](python), tutorials corresponding to https://plot.ly/python/
 - inside the [`apidoc/` directory](apidoc), configuration files for generating
   the API reference documentation (hosted on https://plot.ly/python-api-reference/)
 
 Python packages required to build the doc are listed in
-[`requirements.txt`](requirements.txt) in the `doc` directory. 
+[`requirements.txt`](requirements.txt) in the `doc` directory.
 
 ## Tutorials (`python` directory)
 
@@ -21,15 +21,15 @@ For small edits (e.g., correcting typos) to an existing tutorial, you can simply
 page on Github" link at the top right of the page (e.g. clicking on this link
 on https://plot.ly/python/bar-charts/ will take you to
 https://github.com/plotly/plotly.py/edit/doc-prod/doc/python/bar-charts.md,
-where you can edit the page on Github). 
+where you can edit the page on Github).
 
 For more important edits where you need to run the notebook to check the output,
 clone the repository and setup an environment as described in the [main
 contributing notes](../contributing.md). If you're writing documentation at the
 same time as you are developing a feature, make sure to install with editable
-install (`pip install -e`, as described in [main 
+install (`pip install -e`, as described in [main
 contributing notes](../contributing.md)), so that you only need to restart
-the Jupyter kernel when you have changed the source code of the feature. 
+the Jupyter kernel when you have changed the source code of the feature.
 
 ### Branches
 
@@ -48,7 +48,7 @@ released, or which has just been included but not yet released.
 ### Guidelines
 
 We try to write short, standalone and (almost) self-explaining examples. Most
-examples should focus on a single feature. 
+examples should focus on a single feature.
 
 Checklist
 
@@ -81,17 +81,15 @@ in order to generate the documentation of the API. Sphinx uses the [reST markup
 language](https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html).
 
 Run `make html` inside `apidoc` to build the API doc in the `_build/html`
-directory. 
+directory.
 
 Lists of objects to be documented are found in files corresponding to
 submodules, such as [`plotly.express.rst`](plotly.express.rst). When a new
 object is added to the exposed API, it needs to be added to the corresponding
-file to appear in the API doc.  
+file to appear in the API doc.
 
 Other files
 
 - `css` files are found in `_static`
 - Template files are found in `_templates`. `.rst` templates describe how the
-  autodoc of the different objects should look like.  
-
-
+  autodoc of the different objects should look like.

doc/python/horizontal-legend.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.0
   kernelspec:
     display_name: Python 3
@@ -29,10 +29,12 @@ jupyter:
     name: Legends
     order: 14
     permalink: python/legend/
+    redirect_from: python/horizontal-legend/
     thumbnail: thumbnail/legends.gif
 ---
 
 #### Show Legend
+
 By default the legend is displayed on Plotly charts with multiple traces.
 
 ```python
@@ -240,9 +242,11 @@ fig.update_layout(
 
 fig.show()
 ```
+
 ### Size of Legend Items
 
-In this example [itemsizing](https://plot.ly/python/reference/#layout-legend-itemsizing) attribute determines the legend items symbols remain constant, regardless of how tiny/huge the bubbles would be in the graph.   
+In this example [itemsizing](https://plot.ly/python/reference/#layout-legend-itemsizing) attribute determines the legend items symbols remain constant, regardless of how tiny/huge the bubbles would be in the graph.
+
 ```python
 import plotly.graph_objects as go
 
@@ -266,6 +270,7 @@ fig.update_layout(legend= {'itemsizing': 'constant'})
 
 fig.show()
 ```
+
 #### Grouped Legend
 
 ```python
@@ -364,7 +369,7 @@ fig.show()
 
 Traces corresponding to 2D fields (e.g. `go.Heatmap`, `go.Histogram2d`) or 3D fields (e.g. `go.Isosurface`, `go.Volume`, `go.Cone`) can also appear in the legend. They come with legend icons corresponding to each trace type, which are colored using the same colorscale as the trace.
 
-The example below explores a vector field using several traces. Note that you can click on legend items to hide or to select (with a double click) a specific trace. This will make the exploration of your data easier! 
+The example below explores a vector field using several traces. Note that you can click on legend items to hide or to select (with a double click) a specific trace. This will make the exploration of your data easier!
 
 ```python
 import numpy as np
@@ -382,18 +387,18 @@ mask2 = y>.6
 fig = go.Figure(go.Isosurface(
                       x=x.ravel(), y=y.ravel(), z=z.ravel(),
                       value=magnitude.ravel(),
-                      isomin=1.9, isomax=1.9, 
+                      isomin=1.9, isomax=1.9,
                       colorscale="BuGn",
                       name='isosurface'))
 
 
-fig.add_trace(go.Cone(x=x[mask1], y=y[mask1], z=z[mask1], 
+fig.add_trace(go.Cone(x=x[mask1], y=y[mask1], z=z[mask1],
                       u=u[mask1], v=v[mask1], w=w[mask1],
                       colorscale="Blues",
                       name='cones'
 ))
 fig.add_trace(go.Streamtube(
-                      x=x[mask2], y=y[mask2], z=z[mask2], 
+                      x=x[mask2], y=y[mask2], z=z[mask2],
                       u=u[mask2], v=v[mask2], w=w[mask2],
                       colorscale="Reds",
                       name='streamtubes'
@@ -405,4 +410,5 @@ fig.show()
 ```
 
 #### Reference
+
 See https://plot.ly/python/reference/#layout-legend for more information!

doc/python/legend.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
+      format_version: "1.1"
       jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
@@ -23,7 +23,7 @@ jupyter:
     version: 3.6.7
   plotly:
     description: Learn how to find peaks and valleys on datasets in Python
-    display_as: peak-analysis
+    display_as: advanced_opt
     has_thumbnail: false
     language: python
     layout: base
@@ -35,6 +35,7 @@ jupyter:
 ---
 
 #### Imports
+
 The tutorial below imports [Pandas](https://plot.ly/pandas/intro-to-pandas-tutorial/), and [SciPy](https://www.scipy.org/).
 
 ```python
@@ -43,6 +44,7 @@ from scipy.signal import find_peaks
 ```
 
 #### Import Data
+
 To start detecting peaks, we will import some data on milk production by month:
 
 ```python
@@ -97,6 +99,7 @@ fig.show()
 ```
 
 #### Only Highest Peaks
+
 We can attempt to set our threshold so that we identify as many of the _highest peaks_ that we can.
 
 ```python

doc/python/peak-finding.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
+      format_version: "1.1"
       jupytext_version: 1.2.0
   kernelspec:
     display_name: Python 3
@@ -23,7 +23,7 @@ jupyter:
     version: 3.6.8
   plotly:
     description: How to create charts from csv files with Plotly and Python
-    display_as: databases
+    display_as: advanced_opt
     has_thumbnail: false
     language: python
     layout: base
@@ -34,7 +34,6 @@ jupyter:
     thumbnail: thumbnail/csv.jpg
 ---
 
-
 CSV or comma-delimited-values is a very popular format for storing structured data. In this tutorial, we will see how to plot beautiful graphs using csv data, and Pandas. We will learn how to import csv data from an external source (a url), and plot it using Plotly and pandas.
 
 First we import the data and look at it.
@@ -57,7 +56,6 @@ fig = px.line(df, x = 'AAPL_x', y = 'AAPL_y', title='Apple Share Prices over tim
 fig.show()
 ```
 
-
 ### Plot from CSV with `graph_objects`
 
 ```python
@@ -76,6 +74,6 @@ fig.update_layout(title='Apple Share Prices over time (2014)',
 fig.show()
 ```
 
-
 #### Reference
+
 See https://plot.ly/python/getting-started for more information about Plotly's Python API!

doc/python/plot-data-from-csv.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
+      format_version: "1.1"
       jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
@@ -23,7 +23,7 @@ jupyter:
     version: 3.6.7
   plotly:
     description: Learn how to use Python to make a Random Walk
-    display_as: statistics
+    display_as: advanced_opt
     has_thumbnail: false
     language: python
     layout: base
@@ -36,10 +36,8 @@ jupyter:
 
 A [random walk](https://en.wikipedia.org/wiki/Random_walk) can be thought of as a random process in which a token or a marker is randomly moved around some space, that is, a space with a metric used to compute distance. It is more commonly conceptualized in one dimension ($\mathbb{Z}$), two dimensions ($\mathbb{Z}^2$) or three dimensions ($\mathbb{Z}^3$) in Cartesian space, where $\mathbb{Z}$ represents the set of integers. In the visualizations below, we will be using [scatter plots](https://plot.ly/python/line-and-scatter/) as well as a colorscale to denote the time sequence of the walk.
 
-
 #### Random Walk in 1D
 
-
 The jitter in the data points along the x and y axes are meant to illuminate where the points are being drawn and what the tendancy of the random walk is.
 
 ```python
@@ -137,6 +135,7 @@ fig.show()
 ```
 
 #### Advanced Tip
+
 We can formally think of a 1D random walk as a point jumping along the integer number line. Let $Z_i$ be a random variable that takes on the values +1 and -1. Let this random variable represent the steps we take in the random walk in 1D (where +1 means right and -1 means left). Also, as with the above visualizations, let us assume that the probability of moving left and right is just $\frac{1}{2}$. Then, consider the sum
 
 $$
@@ -164,4 +163,3 @@ $$
 $$
 
 Therefore, we expect our random walk to hover around $0$ regardless of how many steps we take in our walk.
-

doc/python/random-walk.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
+      format_version: "1.1"
       jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
@@ -23,7 +23,7 @@ jupyter:
     version: 3.6.7
   plotly:
     description: Learn how to perform smoothing using various methods in Python.
-    display_as: signal-analysis
+    display_as: advanced_opt
     has_thumbnail: false
     language: python
     layout: base
@@ -34,8 +34,8 @@ jupyter:
     thumbnail: /images/static-image
 ---
 
-
 #### Imports
+
 The tutorial below imports [NumPy](http://www.numpy.org/), [Pandas](https://plot.ly/pandas/intro-to-pandas-tutorial/), [SciPy](https://www.scipy.org/) and [Plotly](https://plot.ly/python/getting-started/).
 
 ```python
@@ -49,6 +49,7 @@ from scipy import signal
 ```
 
 #### Savitzky-Golay Filter
+
 `Smoothing` is a technique that is used to eliminate noise from a dataset. There are many algorithms and methods to accomplish this but all have the same general purpose of 'roughing out the edges' or 'smoothing' some data.
 
 There is reason to smooth data if there is little to no small-scale structure in the data. The danger to this thinking is that one may skew the representation of the data enough to change its percieved meaning, so for the sake of scientific honesty it is an imperative to at the very minimum explain one's reason's for using a smoothing algorithm to their dataset.