docs: Add plotly.js v4 migration guide

.github/workflows/build.yml

@@ -33,10 +33,6 @@ jobs:
       - name: Fetch upstream docs
         run: make fetch_upstream_files
 
-      - name: Set up Mapbox token
-        run: |
-          echo "token: ${{ secrets.MAPBOX_TOKEN }}" > _data/mapbox_token.yml
-
       - name: Build site
         run: |
           python front-matter-ci.py _posts
@@ -49,7 +45,6 @@ jobs:
           md5sum all_static/css/main.css | cut -d ' ' -f 1 > _data/cache_bust_css.yml
           bundle exec jekyll build
           cp python/sitemap.xml _site/python/sitemap.xml
-          rm _data/mapbox_token.yml
 
       - name: Create Percy snapshots
         run: |

_data/display_as.yml

@@ -13,6 +13,9 @@ signal-analysis:
 file_settings:
     reference: '#fundamentals'
     text: Fundamentals
+guide:
+    reference: '#guides'
+    text: Guides
 basic:
     reference: '#basic-charts'
     text: Basic

_data/display_as_py_r_js.yml

@@ -13,6 +13,9 @@ signal-analysis:
 file_settings:
     reference: 'plotly-fundamentals'
     text: Fundamentals
+guide:
+    reference: 'guides'
+    text: Guides
 basic:
     reference: 'basic-charts'
     text: Basic Charts

_data/jsversion.json

@@ -1,3 +1,3 @@
 {
-  "version": "3.6.0"
+  "version": "4.0.0-rc.0"
 }

_data/make_ref_pages.py

@@ -3,13 +3,19 @@
 schema = json.load(open("plotschema.json"))
 
 
-for upperlang in ["Python", "JavaScript", "MATLAB", "R", "Julia", "F#"]:
+# Only Python and JavaScript are regenerated. The MATLAB, R, Julia, and F# reference
+# pages are frozen at whatever schema they were last built from: those languages are no
+# longer maintained, and their pages load pinned older plotly.js bundles (R/ggplot2 on
+# 1.58.4, Julia/MATLAB on 2.35.3 — see _includes/layouts/head.html), so regenerating them
+# from a current schema would document attributes their bundles don't have and drop ones
+# they do. Their existing files under _posts/reference_pages/<lang>/ are left untouched.
+for upperlang in ["Python", "JavaScript"]:
     lang = upperlang.lower()
     lang = "fsharp" if lang == "f#" else lang
     lang = "csharp" if lang == "c#" else lang
     langcode = "plotly_js" if lang == "javascript" else lang
     for attr in [
-        "xaxis", "yaxis", "coloraxis", "scene", "polar", "ternary", "smith", "geo", "mapbox",
+        "xaxis", "yaxis", "coloraxis", "scene", "polar", "ternary", "smith", "geo", "map",
         "sliders", "updatemenus", "annotations", "shapes", "images","selections", "global"
     ]:
         fullattr = "layout" + ("." + attr if attr != "global" else "")

_data/orderings.json

@@ -50,7 +50,6 @@
          "scene",
          "geo",
          "map",
-         "mapbox",
          "polar",
          "smith",
 
@@ -63,8 +62,6 @@
          "sliders",
          "selections",
 
-         "hidesources",
-
          "_deprecated",
          "radialaxis",
          "angularaxis",
@@ -75,15 +72,15 @@
     "traces": [
       "scatter", "scattergl",
         "bar", "pie", "heatmap", "heatmapgl","image",
-        "contour", "table",
+        "contour", "quiver", "table",
 
         "box", "violin", "histogram", "histogram2d", "histogram2dcontour",
 
         "ohlc", "candlestick", "waterfall", "funnel", "funnelarea","indicator",
 
         "scatter3d", "surface", "mesh3d", "cone", "streamtube", "volume", "isosurface",
 
-        "scattergeo", "choropleth", "scattermap", "scattermapbox", "choroplethmap", "choroplethmapbox", "densitymap", "densitymapbox",
+        "scattergeo", "choropleth", "scattermap", "choroplethmap", "densitymap",
 
         "scatterpolar", "scatterpolargl", "barpolar", "scatterternary", "scattersmith", "sunburst", "treemap", "icicle",
 

_includes/layouts/head.html

@@ -35,7 +35,13 @@
   {% endif %}
 
   <!-- Mathjax -->
+  {% if page.language == "r" or page.language == "ggplot2" %}
+  <!-- MathJax v2, kept for the hardcoded plotly.js 1.58.4 bundle loaded on R/ggplot2 pages below -->
   <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"></script>
+  {% else %}
+  <!-- MathJax v3 (tex-svg). Plotly.js v4 removed MathJax v2 support; v3 works with v2.x and v3.x bundles too. -->
+  <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js"></script>
+  {% endif %}
 
   {% if page.language == "plotly_js" %}
   <script src="//cdnjs.cloudflare.com/ajax/libs/d3/3.5.17/d3.min.js"></script>

_includes/layouts/reference-side-nav.html

@@ -1,3 +1,8 @@
+{% comment %}Python and JavaScript track the current plotly.js schema; the other
+languages' reference pages are frozen on older bundles, so they keep the legacy
+entries. See the note at the top of _data/make_ref_pages.py.{% endcomment %}
+{% assign v4ref = false %}
+{% if langue == "javascript" or langue == "python" %}{% assign v4ref = true %}{% endif %}
 <details style="color: white; margin-top: 20px">
   <summary>Simple Traces</summary>
   <nav class="--sidebar-body watch" id="where">
@@ -22,9 +27,11 @@
         <a href="/{{ langue }}/reference/heatmap">Heatmap</a>
       </li>
 
+{% unless v4ref %}
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/heatmapgl">Heatmap GL</a>
       </li>
+{% endunless %}
 
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/image">Image</a>
@@ -34,6 +41,12 @@
         <a href="/{{ langue }}/reference/contour">Contour</a>
       </li>
 
+{% if v4ref %}
+      <li class="--sidebar-item">
+        <a href="/{{ langue }}/reference/quiver">Quiver</a>
+      </li>
+{% endif %}
+
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/table">Table</a>
       </li>
@@ -152,25 +165,32 @@
         <a href="/{{ langue }}/reference/scattermap">Scatter Map</a>
       </li>
 
+{% unless v4ref %}
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/scattermapbox">Scatter Mapbox</a>
       </li>
+{% endunless %}
 
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/choroplethmap">Choropleth Map</a>
       </li>
 
+{% unless v4ref %}
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/choroplethmapbox">Choropleth Mapbox</a>
       </li>
+{% endunless %}
 
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/densitymap">Density Map</a>
       </li>
 
+{% unless v4ref %}
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/densitymapbox">Density Mapbox</a>
       </li>
+{% endunless %}
+
     </ul>
   </nav>
 </details>
@@ -295,7 +315,7 @@
         <a href="/{{ langue }}/reference/layout/geo/">Geo</a>
       </li>
       <li class="--sidebar-item">
-        <a href="/{{ langue }}/reference/layout/mapbox/">Mapbox</a>
+        {% if v4ref %}<a href="/{{ langue }}/reference/layout/map/">Map</a>{% else %}<a href="/{{ langue }}/reference/layout/mapbox/">Mapbox</a>{% endif %}
       </li>
       <li class="--sidebar-item">
         <a href="/{{ langue }}/reference/layout/polar/">Polar</a>

_includes/layouts/side-bar.html

@@ -157,6 +157,9 @@
                         <a href="/javascript/configuration-options/" class="js-splash--navigation-item">Configuration
                             Options</a>
                     </li>
+                    <li class="--sidebar-item">
+                        <a href="/javascript/guides/" class="js-splash--navigation-item">Guides</a>
+                    </li>
                     {% endif %}
 
                     <!-- R Specific -->

_includes/posts/auto_examples.html

@@ -41,8 +41,8 @@ <h3 id="{{ example.name | replace:' ','-' | remove:',' | downcase | strip_html }
               {% assign d3 = "" %}
             {% endif %}
 
-            {% if example.content contains "remember to load MathJax.js" %}
-              {% assign mathjax = "\n\t&lt;script src='//cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML'>&lt;/script&gt;" %}
+            {% if example.content contains "remember to load MathJax" %}
+              {% assign mathjax = "\n\t&lt;script src='https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js'>&lt;/script&gt;" %}
             {% else %}
               {% assign mathjax = "" %}
             {% endif %}
@@ -55,7 +55,7 @@ <h3 id="{{ example.name | replace:' ','-' | remove:',' | downcase | strip_html }
               {% capture unique_myDiv %}myDiv_{{counter}}{% endcapture %}
               <div style="max-width: 100%; margin: auto" id="{{unique_myDiv}}"></div>
               <script>
-                {{ example.content | replace: 'myDiv', unique_myDiv | replace: "your access token", site.data.mapbox_token['token']}}
+                {{ example.content | replace: 'myDiv', unique_myDiv }}
               </script>
             </div>
           {% endif %}

_includes/posts/documentation_eg.html

@@ -8,6 +8,8 @@
 {%- for page in languagelist -%}
 {% if page.display_as == "file_settings" %}
 {% assign file_settings = true %}
+{% elsif page.display_as == "guide" %}
+{% assign guide = true %}
 {% elsif page.display_as == "chart_type" or page.display_as == "basic" %}
 {% assign chart_type = true %}
 {% elsif page.display_as == "statistical" %}
@@ -115,6 +117,30 @@
 </section>
 {% endif %}
 
+{% if guide %}
+<section class="--tutorial-section">
+    <header class="--section-header">
+
+        {% if show_header %}
+        <a href="#guides" name="guides" id="guides">Guides</a>
+        {% endif %}
+
+    </header>
+    <section class="--grid">
+        <ul class="--grid-list">
+            {%- for page in languagelist -%}
+            {% if page.display_as == "guide" %}
+
+            {% include layouts/grid-item.html %}
+
+
+            {% endif %}
+            {%- endfor -%}
+        </ul>
+    </section>
+</section>
+{% endif %}
+
 {% if ai_ml %}
 <section class="--tutorial-section" id="ai_ml">
     <header class="--section-header">

_includes/posts/mainlang_documentation_eg.html

@@ -11,6 +11,8 @@
     {% if page.layout != "langindex" %}
         {% if page.display_as == "file_settings" %}
             {% assign file_settings = true %}
+        {% elsif page.display_as == "guide" %}
+            {% assign guide = true %}
         {% elsif page.display_as == "chart_type" or page.display_as == "basic" %}
             {% assign chart_type = true %}
         {% elsif page.display_as == "statistical" %}
@@ -88,6 +90,39 @@
 </section>
 {% endif %}
 
+{% if guide %}
+<section class="--tutorial-section">
+    <header class="--section-header">
+        <a href="#guides" name="guides" id="guides">Guides</a>
+
+        {% assign forloop_idx = 0 %}
+        {%- for page in languagelist -%}
+            {% if page.display_as == "guide" and page.layout != "langindex" %}
+                {% assign forloop_idx = forloop_idx | plus:1 %}
+            {% endif %}
+        {%- endfor -%}
+
+        {% if forloop_idx >= num_examples %}
+        <a href="/{{language}}/guides" class="langindexlink">More Guides &raquo;</a>
+        {% endif %}
+    </header>
+    <section class="--grid">
+        <ul class="--grid-list">
+
+            {% assign forloop_idx = 0 %}
+
+            {%- for page in languagelist -%}
+                {% if page.display_as == "guide" and page.layout != "langindex" and forloop_idx < num_examples  %}
+                    {% assign forloop_idx = forloop_idx | plus:1 %}
+                    {% include layouts/grid-item.html %}
+                {% endif %}
+            {%- endfor -%}
+
+        </ul>
+    </section>
+</section>
+{% endif %}
+
 
 
 

_posts/plotly_js/2015-04-05-plotly_js-index.html

@@ -77,7 +77,7 @@ <h1>Plotly JavaScript Open Source Graphing Library</h1>
                       x: 0, y: 0, xref: 'paper', yref: 'paper'
                     }]
                   }
-                  Plotly.newPlot(document.getElementById('contour-plot'), [trace], layout, {showLink: false});
+                  Plotly.newPlot(document.getElementById('contour-plot'), [trace], layout);
                 });</code></pre>
 
 
@@ -127,7 +127,7 @@ <h1>Plotly JavaScript Open Source Graphing Library</h1>
                       }
                     };
 
-                    Plotly.newPlot(document.getElementById('wind-speed'), [trace], layout, {showLink: false});
+                    Plotly.newPlot(document.getElementById('wind-speed'), [trace], layout);
                 });</code></pre>
 
 

_posts/plotly_js/2019-07-03-is-plotly-free-js.md

@@ -16,13 +16,15 @@ language: plotly_js
 #### Can I use Plotly.js without signing up to any service?
 
      **Yes.**   You can use Plotly.js to make, view, and distribute charts and maps without registering for any service,
-obtaining any token, or creating any account. The one exception is that to view tile maps
-which use tiles from the Mapbox service (which is optional, as [you can use other tile servers](/javascript/mapbox-layers)), you will need to have a Mapbox token.
+obtaining any token, or creating any account. The built-in tile map styles use open tile providers and need no token. Some
+third-party tile providers you can [point Plotly.js at](/javascript/tile-map-layers) do require an account with that
+provider — Stamen tiles, for instance, are served by Stadia Maps and need a Stadia API key. Sharing a chart with
+[Plotly Cloud](https://cloud.plotly.com) from the modebar requires a Plotly Cloud account, but nothing else does.
 
 #### Can I use Plotly.js offline, without being connected to the internet?
 
      **Yes.**   You can use Plotly.js to make, view, and distribute  graphics totally offline. The one exception is that to view tile maps
-which use tiles from a cloud-hosted service, such as Open Street Maps or Mapbox, you will need a connection to that service. You can view tile maps totally offline if  you run your own local tile server and [use its tiles](/javascript/mapbox-layers).
+which use tiles from a cloud-hosted service, such as OpenStreetMap, you will need a connection to that service. You can view tile maps totally offline if you run your own local tile server and [use its tiles](/javascript/tile-map-layers).
 
 #### Is Dash free?
 

_posts/plotly_js/3d/3d-isosurface/2019-04-16-basic-isosurface.html

@@ -33,4 +33,4 @@
     }
 };
 
-Plotly.newPlot('myDiv', data, layout, {showSendToCloud: true});
+Plotly.newPlot('myDiv', data, layout);

_posts/plotly_js/3d/3d-isosurface/2019-04-16-isosurface-slices.html

@@ -46,5 +46,5 @@
     }
 };
 
-Plotly.newPlot('myDiv', data, layout, {showSendToCloud: true});
+Plotly.newPlot('myDiv', data, layout);
 });

_posts/plotly_js/3d/3d-isosurface/2019-04-16-multiple-isosurfaces-caps.html

@@ -43,6 +43,6 @@
     }
 };
 
-Plotly.newPlot('myDiv', data, layout, {showSendToCloud: true});
+Plotly.newPlot('myDiv', data, layout);
 });
 

_posts/plotly_js/README.md

@@ -122,7 +122,7 @@ Plotly.newPlot('myDiv', data);
   - use "real" data to make the examples realistic and useful for users. 
     - avoid using random or dummy data as much as humanly possible! Should only be a last resort. 
   - upload data files to https://github.com/plotly/datasets as importing data rather than pasting a large chunk of data in the tutorial creates a cleaner example. 
-   - use `var config = {mapboxAccessToken: "your access token"};` if your chart requires Mapbox authentication. `"your access token` will replaced by Plotly's private token at build time. In development mode, you will need to create a `_data/mapboxtoken.yml` file and paste Plotly's non-URL restricted Mapbox key into it. This is available in 1Password.
+   - map examples must not require an API key. The `map` traces (`scattermap`, `choroplethmap`, `densitymap`) use open tile providers, and the `mapboxAccessToken` config option was removed in Plotly.js v4. Keep the example's `layout.map.style` set to a built-in style name or to a keyless style URL, so the chart renders for everyone reading the page. If you want to document a provider that does need a key, put that URL in `markdown_content` as a code snippet for the reader to copy and add their own key to — don't put it in the example itself, where a placeholder key means the rendered chart has no tiles and a real key would be committed to a public repo.
 
 ## Make a Pull Request
   - Ready for your changes to be reviewed? Make a pull request!

_posts/plotly_js/animations/map-animations/2017-08-22-choropleth-animation.html

@@ -52,6 +52,7 @@
     },
     geo:{
        scope: 'world',
+       fitbounds: false,
        countrycolor: 'rgb(255, 255, 255)',
        showland: true,
        landcolor: 'rgb(217, 217, 217)',

_posts/plotly_js/basic/bubble/2015-04-09-bubblechart.html

@@ -12,7 +12,7 @@
   y: [10, 11, 12, 13],
   mode: 'markers',
   marker: {
-    color: ['hsl(0,100,40)', 'hsl(33,100,40)', 'hsl(66,100,40)', 'hsl(99,100,40)'],
+    color: ['hsl(0,100%,40%)', 'hsl(33,100%,40%)', 'hsl(66,100%,40%)', 'hsl(99,100%,40%)'],
     size: [12, 22, 32, 42],
     opacity: [0.6, 0.7, 0.8, 0.9]
   },