Merge pull request #455 from plotly/cam/add-v4-migration-guide

docs: Add plotly.js v4 migration guide

Author: camdecoster

.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"
 }

_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",
 
@@ -398,6 +395,9 @@
  "sortpaths",
 
  "anchor",
+ "arrowref",
+ "lengthmode",
+ "lengthfactor",
  "autocontour",
  "bandwidth",
  "below",

_data/plotschema.json

@@ -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/head.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/reference-side-nav.html

@@ -168,6 +168,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 -->