Sphinx fixes

.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

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!

doc/python/3d-mesh.md

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

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

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

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

@@ -77,7 +77,7 @@ fig.show()
 #### Surface Plot With Contours
 
 
-Display and customize contour data for each axis using the `contours` attribute ([reference](plotly.com/python/reference/#surface-contours)).
+Display and customize contour data for each axis using the `contours` attribute ([reference](plotly.com/python/reference/surface/#surface-contours)).
 
 ```python
 import plotly.graph_objects as go
@@ -99,7 +99,7 @@ fig.update_layout(title='Mt Bruno Elevation', autosize=False,
 fig.show()
 ```
 #### Configure Surface Contour Levels
-This example shows how to slice the surface graph on the desired position for each of x, y and z axis. [contours.x.start](https://plotly.com/python/reference/#surface-contours-x-start) sets the starting contour level value, `end` sets the end of it, and `size` sets the step between each contour level.
+This example shows how to slice the surface graph on the desired position for each of x, y and z axis. [contours.x.start](https://plotly.com/python/reference/surface/#surface-contours-x-start) sets the starting contour level value, `end` sets the end of it, and `size` sets the step between each contour level.
 
 ```python
 import plotly.graph_objects as go
@@ -196,4 +196,4 @@ fig.show()
 #### Reference
 
 
-See https://plotly.com/python/reference/#surface for more information!
+See https://plotly.com/python/reference/surface/ for more information!

doc/python/3d-volume.md

@@ -254,7 +254,7 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/#volume for more information and chart attribute options!
+See https://plotly.com/python/reference/volume/ for more information and chart attribute options!
 
 #### See also
 [3D isosurface documentation](/python/3d-isosurface-plots/)

doc/python/animations.md

@@ -69,7 +69,7 @@ Along with `data` and `layout`, `frames` can be added as a key in a figure objec
 
 #### Adding Control Buttons to Animations
 
-You can add play and pause buttons to control your animated charts by adding an `updatemenus` array to the `layout` of your `figure`. More information on style and placement of the buttons is available in Plotly's [`updatemenus` reference](https://plotly.com/python/reference/#layout-updatemenus).
+You can add play and pause buttons to control your animated charts by adding an `updatemenus` array to the `layout` of your `figure`. More information on style and placement of the buttons is available in Plotly's [`updatemenus` reference](https://plotly.com/python/reference/layout/updatemenus/).
 <br>
 The buttons are defined as follows:
 

doc/python/annotated-heatmap.md

@@ -203,4 +203,4 @@ fig.show()
 
 #### Reference
 
-For more info on Plotly heatmaps, see: https://plotly.com/python/reference/#heatmap.<br> For more info on using colorscales with Plotly see: https://plotly.com/python/heatmap-and-contour-colorscales/ <br>For more info on `ff.create_annotated_heatmap()`, see the [full function reference](https://plotly.com/python-api-reference/generated/plotly.figure_factory.create_annotated_heatmap.html#plotly.figure_factory.create_annotated_heatmap)
+For more info on Plotly heatmaps, see: https://plotly.com/python/reference/heatmap/.<br> For more info on using colorscales with Plotly see: https://plotly.com/python/heatmap-and-contour-colorscales/ <br>For more info on `ff.create_annotated_heatmap()`, see the [full function reference](https://plotly.com/python-api-reference/generated/plotly.figure_factory.create_annotated_heatmap.html#plotly.figure_factory.create_annotated_heatmap)

doc/python/axes.md

@@ -34,14 +34,14 @@ jupyter:
     thumbnail: thumbnail/axes.png
 ---
 
-This tutorial explain how to set the properties of 2-dimensional Cartesian axes, namely [`go.layout.XAxis`](/python/reference/#layout-xaxis) and [`go.layout.YAxis`](python/reference/#layout-xaxis). Other kinds of axes are described in other tutorials:
+This tutorial explain how to set the properties of 2-dimensional Cartesian axes, namely [`go.layout.XAxis`](/python/reference/layout/xaxis/) and [`go.layout.YAxis`](python/reference/layout/xaxis/). Other kinds of axes are described in other tutorials:
 
-- [3D axes](/python/3d-axes) The axis object is [`go.layout.Scene`](/python/reference/#layout-scene)
-- [Polar axes](/python/polar-chart/). The axis object is [`go.layout.Polar`](/python/reference/#layout-polar)
-- [Ternary axes](/python/ternary-plots). The axis object is [`go.layout.Ternary`](/python/reference/#layout-ternary)
-- [Geo axes](/python/map-configuration/). The axis object is [`go.layout.Geo`](/python/reference/#layout-geo)
-- [Mapbox axes](/python/mapbox-layers/). The axis object is [`go.layout.Mapbox`](/python/reference/#layout-mapbox)
-- [Color axes](/python/colorscales/). The axis object is [`go.layout.Coloraxis`](/python/reference/#layout-coloraxis).
+- [3D axes](/python/3d-axes) The axis object is [`go.layout.Scene`](/python/reference/layout/scene/)
+- [Polar axes](/python/polar-chart/). The axis object is [`go.layout.Polar`](/python/reference/layout/polar/)
+- [Ternary axes](/python/ternary-plots). The axis object is [`go.layout.Ternary`](/python/reference/layout/ternary/)
+- [Geo axes](/python/map-configuration/). The axis object is [`go.layout.Geo`](/python/reference/layout/geo/)
+- [Mapbox axes](/python/mapbox-layers/). The axis object is [`go.layout.Mapbox`](/python/reference/layout/mapbox/)
+- [Color axes](/python/colorscales/). The axis object is [`go.layout.Coloraxis`](/python/reference/layout/coloraxis/).
 
 **See also** the tutorials on [subplots](/python/subplots) and [multiple axes](/python/multiple-axes/).
 
@@ -777,4 +777,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#layout-xaxis and https://plotly.com/python/reference/#layout-yaxis for more information and chart attribute options!
+See https://plotly.com/python/reference/layout/xaxis/ and https://plotly.com/python/reference/layout/yaxis/ for more information and chart attribute options!

doc/python/bar-charts.md

@@ -372,7 +372,7 @@ fig.show()
 
 ### Bar Chart with Sorted or Ordered Categories
 
-Set `categoryorder` to `"category ascending"` or `"category descending"` for the alphanumerical order of the category names or `"total ascending"` or `"total descending"` for numerical order of values. [categoryorder](https://plotly.com/python/reference/#layout-xaxis-categoryorder) for more information. Note that sorting the bars by a particular trace isn't possible right now - it's only possible to sort by the total values. Of course, you can always sort your data _before_ plotting it if you need more customization.
+Set `categoryorder` to `"category ascending"` or `"category descending"` for the alphanumerical order of the category names or `"total ascending"` or `"total descending"` for numerical order of values. [categoryorder](https://plotly.com/python/reference/layout/xaxis/#layout-xaxis-categoryorder) for more information. Note that sorting the bars by a particular trace isn't possible right now - it's only possible to sort by the total values. Of course, you can always sort your data _before_ plotting it if you need more customization.
 
 This example orders the bar chart alphabetically with `categoryorder: 'category ascending'`
 
@@ -442,4 +442,4 @@ fig.show()
 
 ### Reference
 
-See https://plotly.com/python/reference/#bar for more information and chart attribute options!
+See https://plotly.com/python/reference/bar/ for more information and chart attribute options!

doc/python/box-plots.md

@@ -134,7 +134,7 @@ fig.show()
 
 ## Box plot with go.Box
 
-If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Box` class from `plotly.graph_objects`](/python/graph-objects/). All available options for `go.Box` are described in the reference page https://plotly.com/python/reference/#box.
+If Plotly Express does not provide a good starting point, it is also possible to use [the more generic `go.Box` class from `plotly.graph_objects`](/python/graph-objects/). All available options for `go.Box` are described in the reference page https://plotly.com/python/reference/box/.
 
 ### Basic Box Plot
 
@@ -502,4 +502,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#box for more information and chart attribute options!
+See https://plotly.com/python/reference/box/ for more information and chart attribute options!

doc/python/bubble-charts.md

@@ -91,8 +91,8 @@ fig.show()
 
 To scale the bubble size, use the attribute `sizeref`. We recommend using the following formula to calculate a `sizeref` value:<br>
 `sizeref = 2. * max(array of size values) / (desired maximum marker size ** 2)`<br>
-Note that setting 'sizeref' to a value greater than 1, decreases the rendered marker sizes, while setting 'sizeref' to less than 1, increases the rendered marker sizes. See https://plotly.com/python/reference/#scatter-marker-sizeref for more information.
-Additionally, we recommend setting the sizemode attribute: https://plotly.com/python/reference/#scatter-marker-sizemode to area.
+Note that setting 'sizeref' to a value greater than 1, decreases the rendered marker sizes, while setting 'sizeref' to less than 1, increases the rendered marker sizes. See https://plotly.com/python/reference/scatter/#scatter-marker-sizeref for more information.
+Additionally, we recommend setting the sizemode attribute: https://plotly.com/python/reference/scatter/#scatter-marker-sizemode to area.
 
 ```python
 import plotly.graph_objects as go
@@ -222,4 +222,4 @@ fig.show()
 
 ### Reference
 
-See https://plotly.com/python/reference/#scatter for more information and chart attribute options!
+See https://plotly.com/python/reference/scatter/ for more information and chart attribute options!