merge doc-prod into master

Author: nicolaskruchten

.circleci/config.yml

@@ -374,7 +374,7 @@ jobs:
     docker:
       # specify the version you desire here
       # use `-browsers` prefix for selenium tests, e.g. `3.6.1-browsers`
-      - image: circleci/python:3.6.8-node
+      - image: circleci/python:3.7-stretch-node-browsers
 
         working_directory: ~/project
 
@@ -400,12 +400,13 @@ jobs:
             . venv/bin/activate
             npm install electron@1.8.4
             npm install orca
+            pip install -U pip
             pip uninstall -y plotly
             pip install -r requirements.txt
             if [ "${CIRCLE_BRANCH}" != "doc-prod" ]; then
               pip uninstall -y plotly
               cd ../packages/python/plotly
-              python3 setup.py install
+              pip install -e .
               cd ../../../doc
             fi
             echo 'export PATH="/home/circleci/project/doc/node_modules/.bin:$PATH"' >> $BASH_ENV
@@ -463,6 +464,15 @@ jobs:
           command: |
             cd doc
             . venv/bin/activate
+            # For the API doc, we need to use the local version of plotly
+            # since we are tweaking the source because of
+            # graph_objs/graph_objects
+            if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then
+              pip uninstall -y plotly
+              cd ../packages/python/plotly
+              pip install -e .
+              cd ../../../doc
+            fi
             cd apidoc
             make html
             if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then
@@ -478,12 +488,14 @@ jobs:
               rm -rf .git
               cd ../..
             fi
-
             cd ../..
 
       - store_artifacts:
           path: doc/build
           destination: doc/build
+      - store_artifacts:
+          path: doc/apidoc/_build/
+          destination: doc/apidoc/_build/
 
 workflows:
   version: 2

binder/requirements.txt

@@ -16,3 +16,5 @@ datashader
 pyarrow
 cufflinks==0.17.3
 kaleido
+scikit-learn
+umap-learn

doc/Makefile

@@ -38,6 +38,7 @@ $(HTML_DIR)/2019-07-03-%.html: $(IPYNB_DIR)/%.ipynb
 	@mkdir -p $(FAIL_DIR)
 	@echo "[nbconvert]  $<"
 	@jupyter nbconvert $< --to html --template nb.tpl \
+			--ExecutePreprocessor.timeout=600\
 	  	--output-dir $(HTML_DIR) --output 2019-07-03-$*.html \
 	  	--execute > $(FAIL_DIR)/$* 2>&1  && rm -f $(FAIL_DIR)/$*
 

doc/apidoc/Makefile

@@ -22,17 +22,24 @@ help:
 	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*.py
 	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*/*.py
 	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*/*/*.py
+	# Copy _plotly_utils file so that they appear in the API doc
 	cp ../../packages/python/plotly/_plotly_utils/colors/sequential.py ../../packages/python/plotly/_plotly_utils/colors/diverging.py ../../packages/python/plotly/_plotly_utils/colors/qualitative.py ../../packages/python/plotly/_plotly_utils/colors/cyclical.py ../../packages/python/plotly/_plotly_utils/colors/colorbrewer.py ../../packages/python/plotly/_plotly_utils/colors/carto.py ../../packages/python/plotly/_plotly_utils/colors/cmocean.py ../../packages/python/plotly/plotly/colors
 	cp ../../packages/python/plotly/_plotly_utils/colors/sequential.py ../../packages/python/plotly/_plotly_utils/colors/diverging.py ../../packages/python/plotly/_plotly_utils/colors/qualitative.py ../../packages/python/plotly/_plotly_utils/colors/cyclical.py ../../packages/python/plotly/_plotly_utils/colors/colorbrewer.py ../../packages/python/plotly/_plotly_utils/colors/carto.py ../../packages/python/plotly/_plotly_utils/colors/cmocean.py ../../packages/python/plotly/plotly/express/colors
+	# Run sphinx-apidoc script to create hierarchy of rst files to generate
+	# docstrings. The first path is the one to process, the following ones
+	# are excluded from the search.
+	rm -rf _build generated
 	sphinx-apidoc -M -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api
+	# Run sphinx-build to build html pages from the rst pages
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	git checkout -- ../../packages/python/plotly/plotly/graph_objs
+	# Remove files which were added only for docstring generation
 	rm ../../packages/python/plotly/plotly/colors/diverging.py ../../packages/python/plotly/plotly/colors/sequential.py ../../packages/python/plotly/plotly/colors/qualitative.py ../../packages/python/plotly/plotly/colors/cyclical.py ../../packages/python/plotly/plotly/colors/colorbrewer.py ../../packages/python/plotly/plotly/colors/carto.py ../../packages/python/plotly/plotly/colors/cmocean.py
 	rm ../../packages/python/plotly/plotly/express/colors/diverging.py ../../packages/python/plotly/plotly/express/colors/sequential.py ../../packages/python/plotly/plotly/express/colors/qualitative.py ../../packages/python/plotly/plotly/express/colors/cyclical.py ../../packages/python/plotly/plotly/express/colors/colorbrewer.py ../../packages/python/plotly/plotly/express/colors/carto.py ../../packages/python/plotly/plotly/express/colors/cmocean.py
 	rename 's/graph_objs/graph_objects/' _build/html/*.html _build/html/generated/*.html
 	mv _build/html/generated/plotly.graph_objs.html _build/html/generated/plotly.graph_objects.html
-	sed -i 's/graph_objs/graph_objects/g' _build/html/*.html 
-	sed -i 's/graph_objs/graph_objects/g' _build/html/*.inv 
-	sed -i 's/graph_objs/graph_objects/g' _build/html/*.js 
-	sed -i 's/graph_objs/graph_objects/g' _build/html/generated/*.html 
+	sed -i 's/graph_objs/graph_objects/g' _build/html/*.html
+	sed -i 's/graph_objs/graph_objects/g' _build/html/*.inv
+	sed -i 's/graph_objs/graph_objects/g' _build/html/*.js
+	sed -i 's/graph_objs/graph_objects/g' _build/html/generated/*.html
 	sed -i 's/graph_objs/graph_objects/g' _build/html/generated/generated/*.html

doc/python/2D-Histogram.md

@@ -137,7 +137,7 @@ fig = go.Figure(go.Histogram2d(x=x, y=y, histnorm='probability',
 fig.show()
 ```
 ### Sharing bin settings between 2D Histograms
-This example shows how to use [bingroup](https://plotly.com/python/reference/#histogram-bingroup) attribute to have a compatible bin settings for both histograms. To define `start`, `end` and `size` value of x-axis and y-axis seperatly, set [ybins](https://plotly.com/python/reference/#histogram2dcontour-ybins) and `xbins`.
+This example shows how to use [bingroup](https://plotly.com/python/reference/histogram/#histogram-bingroup) attribute to have a compatible bin settings for both histograms. To define `start`, `end` and `size` value of x-axis and y-axis seperatly, set [ybins](https://plotly.com/python/reference/histogram2dcontour/#histogram2dcontour-ybins) and `xbins`.
 
 ```python
 import plotly.graph_objects as go
@@ -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

@@ -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/3d-bubble-charts.md

@@ -107,7 +107,7 @@ fig = go.Figure(data=go.Scatter3d(
     mode = 'markers',
     marker = dict(
         sizemode = 'diameter',
-        sizeref = 750, # info on sizeref: https://plotly.com/python/reference/#scatter-marker-sizeref
+        sizeref = 750, # info on sizeref: https://plotly.com/python/reference/scatter/#scatter-marker-sizeref
         size = planet_diameter,
         color = planet_colors,
         )
@@ -146,7 +146,7 @@ fig = go.Figure(go.Scatter3d(
     mode = 'markers',
     marker = dict(
         sizemode = 'diameter',
-        sizeref = 750, # info on sizeref: https://plotly.com/python/reference/#scatter-marker-sizeref
+        sizeref = 750, # info on sizeref: https://plotly.com/python/reference/scatter/#scatter-marker-sizeref
         size = planet_diameter,
         color = temperatures,
         colorbar_title = 'Mean<br>Temperature',
@@ -166,4 +166,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#scatter3d and https://plotly.com/python/reference/#scatter-marker-sizeref <br>for more information and chart attribute options!
+See https://plotly.com/python/reference/scatter3d/ and https://plotly.com/python/reference/scatter/#scatter-marker-sizeref <br>for more information and chart attribute options!

doc/python/3d-camera-controls.md

@@ -290,4 +290,4 @@ fig.show()
 #### Reference
 
 
-See https://plotly.com/python/reference/#layout-scene-camera for more information and chart attribute options!
+See https://plotly.com/python/reference/layout/scene/#layout-scene-camera for more information and chart attribute options!

doc/python/3d-isosurface-plots.md

@@ -235,4 +235,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/#isosurface for more information and chart attribute options!
+See https://plotly.com/python/reference/isosurface/ for more information and chart attribute options!

doc/python/3d-line-plots.md

@@ -120,4 +120,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#scatter3d-marker-line for more information and chart attribute options!
+See https://plotly.com/python/reference/scatter3d/#scatter3d-marker-line for more information and chart attribute options!