Merge pull request #5792 from plotly/adjust-image-test-docs

improve CONTRIBUTING guidelines for creating & updating baselines

Author: archmoj

.circleci/env_image.sh

@@ -1,6 +1,8 @@
 #!/bin/sh
+# install required fonts
 sudo apt-get install fonts-liberation2 fonts-open-sans fonts-noto-cjk fonts-noto-color-emoji && \
 sudo python3 .circleci/download_google_fonts.py && \
 sudo cp -r .circleci/fonts/ /usr/share/ && \
 sudo fc-cache -f && \
+# install kaleido & plotly
 sudo python3 -m pip install kaleido==0.2.1 plotly==5.1.0 --progress-bar off

CONTRIBUTING.md

@@ -207,17 +207,40 @@ npm run test-jasmine -- --help
 npm run test-jasmine -- --info
 ```
 
-### Draft new baseline
-Install fonts and tools
+### Draft new baselines
+#### With docker:
+> If you prefer using docker each time you need to
+```sh
+docker run -it -v "$(pwd)":/plotly.js circleci/python:3.8.9 bash
+# then inside the docker
+cd plotly.js
+sudo bash .circleci/env_image.sh
+```
+
+#### Without docker:
+> Otherwise you may need to install `python 3.8`
+Then upgrade `pip` if needed
 ```sh
-# install required fonts (if missing) on ubuntu
-sudo cp -r .circleci/fonts/ /usr/share/ && sudo fc-cache -f
-# upgrade pip (if needed)
 python3 -m pip install --upgrade pip
-# install kaleido
-python3 -m pip install kaleido
-# install plotly
-python3 -m pip install plotly
+```
+
+To install required fonts and tools see this [shell script](https://github.com/plotly/plotly.js/blob/master/.circleci/env_image.sh).
+
+#### Scripts to generate/update new baselines with/without docker:
+```sh
+python3 test/image/make_baseline.py = mock_1 mock_2
+```
+
+> Alternatively using npm & node.js (which are not available in the python docker by default)
+
+```sh
+npm run baseline mock_1 mock_2
+```
+
+Or
+
+```sh
+npm run baseline mock_*
 ```
 
 **IMPORTANT:** the `baseline`, `test-image` and `test-export` scripts do **not** bundle the source files before