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

_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",

_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)',