Sphinx fixes (against doc-prod) (#2687)

* add sphinx apidoc to circleci artifacts

* added bison to try to fix ci

* build the doc on python 3.7 (lazy import)

* use local plotly for all branches (pip install -e . is required because of our tweaks in the source code)

Author: emmanuelle

.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/requirements.txt

@@ -23,5 +23,5 @@ recommonmark
 pathlib
 python-frontmatter
 datashader
-pyarrow
+pyarrow 
 cufflinks==0.17.3