Fix thumbnail generation and update images (#395)

* Fix and improve example image generation * Updating images * Cleanup
maplibre · Feb 16, 2023 · eea2502 · eea2502
1 parent 9164b4d
commit eea2502
Show file tree

Hide file tree

Showing 125 changed files with 110 additions and 86 deletions.
diff --git a/README.md b/README.md
@@ -54,15 +54,18 @@ In content area of the markdown page include an extended description of the exam
 
 In the `.html` file, write the HTML and JavaScript constituting the example.
 
-* Do **not** include an access token in the example code. The access token will be inserted automatically by the template, using the current logged in user's default public token, or a placeholder `<insert token here>` string if the user is not logged in.
+* Do **not** include a MapTiler access token in the example code. The access token will be inserted automatically by the template, using the current logged in user's default public token, or a placeholder `<insert token here>` string if the user is not logged in.
 * On commit, Prettier will format the code for all files, including HTML.
 
-Every example **must** have an accompanying image. To get an image, run the site locally and take a screenshot of the rendered map in the example:
+Every example **must** have an accompanying image.
 
-1. Run `npm run create-image <example-file-name> <mapbox-access-token>`. The script will take a screenshot of the map in the example and save it to `docs/img/src/`. Commit the image.
-2. Run `npm start` to verify that your example image is loading as expected.
+1. Ensure that you have a build of the latest `maplibre-gl-js` in the neighboring directory (see below).
+2. Run `npm run create-image <example-file-name>`. The script will take a screenshot of the map in the example and save it to `docs/img/src/`. Commit the image.
+3. Run `npm start` to verify that your example image is loading as expected.
 
-💡 If `npm run create-image` does not generate an ideal image. You can also take a screenshot of it yourself by running the site locally with `npm start` and taking a screenshot of the example map in PNG format. Resize it to 1200 x 500 pixels and save it in the `docs/img/src` folder.
+For some examples, `npm run create-image` does not generate an ideal image. In these cases, you can interact with the map after running `ncreate-image`, or take a screenshot yourself by running the site locally with `npm start`, take a screenshot and save it in the `docs/img/src` folder.
+
+To regenerate all images, run `npm run create-image all`. Note that this doesn't support interaction and examples that require manual interaction (e.g. popups). will need to be manually redone afterward. This feature is experimental and may crash before sucessfully generating all examples.
 
 ## Running the Documentation Server Locally
 
@@ -77,7 +80,7 @@ The command will print the URL you can use to view the documentation.
 💡 If you receive an error related to `@mapbox/appropriate-images`, try `nvm use && npm start`.
 
 The examples section of the locally run documentation will use the GL JS version located in `../maplibre-gl-js/dist`,
-so make sure to have a working minified build in your local copy of the `maplibre-gl-js` repo (not the submodule; clone `maplibre-gl-js` into the same directory as `maplibre-gl-js-docs` and run `npm build-dist` there).
+so make sure to have a working minified build in your local copy of the `maplibre-gl-js` repo (not the submodule; clone `maplibre-gl-js` into the same directory as `maplibre-gl-js-docs` and run `npm run build-dist` there).
 
 
 ## Committing and Publishing Documentation

diff --git a/docs/bin/create-image.js b/docs/bin/create-image.js
@@ -0,0 +1,101 @@
+// eslint-disable-line
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import pack from 'maplibre-gl/package.json' assert { type: 'json' };
+import puppeteer from 'puppeteer';
+
+const exampleName = process.argv[2];
+const binPath = path.dirname(fileURLToPath(import.meta.url));
+const examplePath = path.resolve(binPath, '..', 'pages', 'example');
+
+const browser = await puppeteer.launch({ headless: exampleName === 'all' });
+
+let page = await browser.newPage();
+// set viewport and double deviceScaleFactor to get a closer shot of the map
+await page.setViewport({
+    width: 600,
+    height: 600,
+    deviceScaleFactor: 2
+});
+
+async function createImage(nameWithExtension) {
+    const exampleName = nameWithExtension
+        .replace('.html', '')
+        .replace('.js', '');
+    // get the example contents/snippet
+    const snippet = fs.readFileSync(
+        path.resolve(examplePath, `${exampleName}.html`),
+        'utf-8'
+    );
+    // create an HTML page to display the example snippet
+    const html = `<!DOCTYPE html>
+    <html>
+    <head>
+    <meta charset='utf-8' />
+    <script src='https://unpkg.com/maplibre-gl@${pack.version}/dist/maplibre-gl.js'></script>
+    <link href='https://unpkg.com/maplibre-gl@${pack.version}/dist/maplibre-gl.css' rel='stylesheet' />
+    <style>
+    body { margin:0; padding:0; }
+    #map { position: absolute; top:0; bottom:0; width: 600px; max-height: 300px; }
+    </style>
+    </head>
+    <body>
+    ${snippet}
+    </body>
+    </html>`;
+
+    // eslint-disable-next-line xss/no-mixed-html
+    await page.setContent(html);
+
+    // Wait for map to load, then wait two more seconds for images, etc. to load.
+    await page
+        .waitForFunction('map.loaded()')
+        .then(async () => {
+            // Wait for 5 seconds on 3d model examples, since this takes longer to load.
+            const waitTime = exampleName.includes('3d-model') ? 5000 : 1500;
+            // eslint-disable-next-line es/no-promise
+            await new Promise(function (resolve) {
+                console.log(`waiting for ${waitTime} ms`);
+                setTimeout(resolve, waitTime);
+            });
+        })
+        // map.loaded() does not evaluate to true within 3 seconds, it's probably an animated example.
+        // In this case we take the screenshot immediately.
+        .catch(() => {
+            console.log(`Timed out waiting for map load on ${exampleName}.`);
+        });
+
+    await page
+        .screenshot({
+            path: `./docs/img/src/${exampleName}.png`,
+            type: 'png',
+            clip: {
+                x: 0,
+                y: 0,
+                width: 600,
+                height: 250
+            }
+        })
+        .then(() => console.log(`Created ./docs/img/src/${exampleName}.png`))
+        .catch((err) => {
+            console.log(err);
+        });
+}
+
+if (exampleName === 'all') {
+    const allFiles = fs.readdirSync(examplePath);
+    const files = allFiles.filter((file) => /\.html$/.test(file));
+    console.log(`Generating ${files.length} images.`);
+    for (const file of files) {
+        await createImage(file);
+    }
+} else if (exampleName) {
+    await createImage(exampleName);
+} else {
+    throw new Error(
+        '\n  Usage: npm run create-image <file-name>\nExample: npm run create-image 3d-buildings'
+    );
+}
+
+await browser.close();
diff --git a/docs/bin/create-image.ts b/docs/bin/create-image.ts
diff --git a/docs/img/src/3d-buildings.png b/docs/img/src/3d-buildings.png
diff --git a/docs/img/src/3d-extrusion-floorplan.png b/docs/img/src/3d-extrusion-floorplan.png
diff --git a/docs/img/src/3d-terrain.png b/docs/img/src/3d-terrain.png
diff --git a/docs/img/src/add-3d-model-babylon.png b/docs/img/src/add-3d-model-babylon.png
diff --git a/docs/img/src/add-3d-model.png b/docs/img/src/add-3d-model.png
diff --git a/docs/img/src/add-a-marker.png b/docs/img/src/add-a-marker.png
diff --git a/docs/img/src/add-image-animated.png b/docs/img/src/add-image-animated.png
diff --git a/docs/img/src/add-image-generated.png b/docs/img/src/add-image-generated.png
diff --git a/docs/img/src/add-image-missing-generated.png b/docs/img/src/add-image-missing-generated.png
diff --git a/docs/img/src/add-image-stretchable.png b/docs/img/src/add-image-stretchable.png
diff --git a/docs/img/src/add-image.png b/docs/img/src/add-image.png
diff --git a/docs/img/src/adjust-layer-opacity.png b/docs/img/src/adjust-layer-opacity.png
diff --git a/docs/img/src/animate-a-line.png b/docs/img/src/animate-a-line.png
diff --git a/docs/img/src/animate-camera-around-point.png b/docs/img/src/animate-camera-around-point.png
diff --git a/docs/img/src/animate-images.png b/docs/img/src/animate-images.png
diff --git a/docs/img/src/animate-marker.png b/docs/img/src/animate-marker.png
diff --git a/docs/img/src/animate-point-along-line.png b/docs/img/src/animate-point-along-line.png
diff --git a/docs/img/src/animate-point-along-route.png b/docs/img/src/animate-point-along-route.png
diff --git a/docs/img/src/attribution-position.png b/docs/img/src/attribution-position.png
diff --git a/docs/img/src/camera-animation.png b/docs/img/src/camera-animation.png
diff --git a/docs/img/src/canvas-source.png b/docs/img/src/canvas-source.png
diff --git a/docs/img/src/center-on-symbol.png b/docs/img/src/center-on-symbol.png
diff --git a/docs/img/src/change-building-color-based-on-zoom-level.png b/docs/img/src/change-building-color-based-on-zoom-level.png
diff --git a/docs/img/src/change-case-of-labels.png b/docs/img/src/change-case-of-labels.png
diff --git a/docs/img/src/check-for-support.png b/docs/img/src/check-for-support.png
diff --git a/docs/img/src/cluster-html.png b/docs/img/src/cluster-html.png
diff --git a/docs/img/src/cluster.png b/docs/img/src/cluster.png
diff --git a/docs/img/src/color-switcher.png b/docs/img/src/color-switcher.png
diff --git a/docs/img/src/custom-marker-icons.png b/docs/img/src/custom-marker-icons.png
diff --git a/docs/img/src/custom-style-id.png b/docs/img/src/custom-style-id.png
diff --git a/docs/img/src/custom-style-layer.png b/docs/img/src/custom-style-layer.png
diff --git a/docs/img/src/dancing-buildings.png b/docs/img/src/dancing-buildings.png
diff --git a/docs/img/src/data-driven-circle-colors.png b/docs/img/src/data-driven-circle-colors.png
diff --git a/docs/img/src/data-driven-lines.png b/docs/img/src/data-driven-lines.png
diff --git a/docs/img/src/data-join.png b/docs/img/src/data-join.png
diff --git a/docs/img/src/disable-rotation.png b/docs/img/src/disable-rotation.png
diff --git a/docs/img/src/disable-scroll-zoom.png b/docs/img/src/disable-scroll-zoom.png
diff --git a/docs/img/src/display-and-style-rich-text-labels.png b/docs/img/src/display-and-style-rich-text-labels.png
diff --git a/docs/img/src/drag-a-marker.png b/docs/img/src/drag-a-marker.png
diff --git a/docs/img/src/drag-a-point.png b/docs/img/src/drag-a-point.png
diff --git a/docs/img/src/fallback-image.png b/docs/img/src/fallback-image.png
diff --git a/docs/img/src/fill-pattern.png b/docs/img/src/fill-pattern.png
diff --git a/docs/img/src/filter-features-within-map-view.png b/docs/img/src/filter-features-within-map-view.png
diff --git a/docs/img/src/filter-markers-by-input.png b/docs/img/src/filter-markers-by-input.png
diff --git a/docs/img/src/filter-markers.png b/docs/img/src/filter-markers.png
diff --git a/docs/img/src/fitbounds.png b/docs/img/src/fitbounds.png
diff --git a/docs/img/src/flyto-options.png b/docs/img/src/flyto-options.png
diff --git a/docs/img/src/flyto.png b/docs/img/src/flyto.png
diff --git a/docs/img/src/forward-geocode-custom-data.png b/docs/img/src/forward-geocode-custom-data.png
diff --git a/docs/img/src/fullscreen.png b/docs/img/src/fullscreen.png
diff --git a/docs/img/src/game-controls.png b/docs/img/src/game-controls.png
diff --git a/docs/img/src/geocoder.png b/docs/img/src/geocoder.png
diff --git a/docs/img/src/geojson-layer-in-stack.png b/docs/img/src/geojson-layer-in-stack.png
diff --git a/docs/img/src/geojson-line.png b/docs/img/src/geojson-line.png
diff --git a/docs/img/src/geojson-markers.png b/docs/img/src/geojson-markers.png
diff --git a/docs/img/src/geojson-polygon.png b/docs/img/src/geojson-polygon.png
diff --git a/docs/img/src/heatmap-layer.png b/docs/img/src/heatmap-layer.png
diff --git a/docs/img/src/hillshade.png b/docs/img/src/hillshade.png
diff --git a/docs/img/src/hover-styles.png b/docs/img/src/hover-styles.png
diff --git a/docs/img/src/image-on-a-map.png b/docs/img/src/image-on-a-map.png
diff --git a/docs/img/src/interactive-false.png b/docs/img/src/interactive-false.png
diff --git a/docs/img/src/jump-to.png b/docs/img/src/jump-to.png
diff --git a/docs/img/src/language-switch.png b/docs/img/src/language-switch.png
diff --git a/docs/img/src/layer-background.png b/docs/img/src/layer-background.png
diff --git a/docs/img/src/layer-circle.png b/docs/img/src/layer-circle.png
diff --git a/docs/img/src/layer-fill-extrusion.png b/docs/img/src/layer-fill-extrusion.png
diff --git a/docs/img/src/layer-fill.png b/docs/img/src/layer-fill.png
diff --git a/docs/img/src/layer-heatmap.png b/docs/img/src/layer-heatmap.png
diff --git a/docs/img/src/layer-hillshade.png b/docs/img/src/layer-hillshade.png
diff --git a/docs/img/src/layer-line.png b/docs/img/src/layer-line.png
diff --git a/docs/img/src/layer-raster.png b/docs/img/src/layer-raster.png
diff --git a/docs/img/src/layer-symbol.png b/docs/img/src/layer-symbol.png
diff --git a/docs/img/src/line-across-180th-meridian.png b/docs/img/src/line-across-180th-meridian.png
diff --git a/docs/img/src/line-gradient.png b/docs/img/src/line-gradient.png
diff --git a/docs/img/src/live-geojson.png b/docs/img/src/live-geojson.png
diff --git a/docs/img/src/live-update-feature.png b/docs/img/src/live-update-feature.png
diff --git a/docs/img/src/local-geojson-experimental.png b/docs/img/src/local-geojson-experimental.png
diff --git a/docs/img/src/local-geojson.png b/docs/img/src/local-geojson.png
diff --git a/docs/img/src/local-ideographs.png b/docs/img/src/local-ideographs.png
diff --git a/docs/img/src/locate-user.png b/docs/img/src/locate-user.png
diff --git a/docs/img/src/map-tiles.png b/docs/img/src/map-tiles.png
diff --git a/docs/img/src/mapbox-gl-compare.png b/docs/img/src/mapbox-gl-compare.png
diff --git a/docs/img/src/mapbox-gl-draw.png b/docs/img/src/mapbox-gl-draw.png
diff --git a/docs/img/src/mapbox-gl-rtl-text.png b/docs/img/src/mapbox-gl-rtl-text.png
diff --git a/docs/img/src/marker-from-geocode.png b/docs/img/src/marker-from-geocode.png
diff --git a/docs/img/src/measure.png b/docs/img/src/measure.png
diff --git a/docs/img/src/mouse-position.png b/docs/img/src/mouse-position.png
diff --git a/docs/img/src/multiple-geometries.png b/docs/img/src/multiple-geometries.png
diff --git a/docs/img/src/navigation.png b/docs/img/src/navigation.png
diff --git a/docs/img/src/offset-vanishing-point-with-padding.png b/docs/img/src/offset-vanishing-point-with-padding.png
diff --git a/docs/img/src/placeholder.png b/docs/img/src/placeholder.png
diff --git a/docs/img/src/playback-locations.png b/docs/img/src/playback-locations.png
diff --git a/docs/img/src/point-from-geocoder-result.png b/docs/img/src/point-from-geocoder-result.png
diff --git a/docs/img/src/polygon-popup-on-click.png b/docs/img/src/polygon-popup-on-click.png
diff --git a/docs/img/src/popup-on-click.png b/docs/img/src/popup-on-click.png
diff --git a/docs/img/src/popup-on-hover.png b/docs/img/src/popup-on-hover.png
diff --git a/docs/img/src/popup.png b/docs/img/src/popup.png
diff --git a/docs/img/src/query-similar-features.png b/docs/img/src/query-similar-features.png
diff --git a/docs/img/src/queryrenderedfeatures-around-point.png b/docs/img/src/queryrenderedfeatures-around-point.png
diff --git a/docs/img/src/queryrenderedfeatures.png b/docs/img/src/queryrenderedfeatures.png
diff --git a/docs/img/src/render-world-copies.png b/docs/img/src/render-world-copies.png
diff --git a/docs/img/src/restrict-bounds.png b/docs/img/src/restrict-bounds.png
diff --git a/docs/img/src/satellite-map.png b/docs/img/src/satellite-map.png
diff --git a/docs/img/src/scroll-fly-to.png b/docs/img/src/scroll-fly-to.png
diff --git a/docs/img/src/set-perspective.png b/docs/img/src/set-perspective.png
diff --git a/docs/img/src/set-popup.png b/docs/img/src/set-popup.png
diff --git a/docs/img/src/setstyle.png b/docs/img/src/setstyle.png
diff --git a/docs/img/src/simple-map.png b/docs/img/src/simple-map.png
diff --git a/docs/img/src/style-ocean-depth-data.png b/docs/img/src/style-ocean-depth-data.png
diff --git a/docs/img/src/third-party.png b/docs/img/src/third-party.png
diff --git a/docs/img/src/timeline-animation.png b/docs/img/src/timeline-animation.png
diff --git a/docs/img/src/toggle-interaction-handlers.png b/docs/img/src/toggle-interaction-handlers.png
diff --git a/docs/img/src/toggle-layers.png b/docs/img/src/toggle-layers.png
diff --git a/docs/img/src/toggle-worldviews.png b/docs/img/src/toggle-worldviews.png
diff --git a/docs/img/src/updating-choropleth.png b/docs/img/src/updating-choropleth.png
diff --git a/docs/img/src/using-box-queryrenderedfeatures.png b/docs/img/src/using-box-queryrenderedfeatures.png
diff --git a/docs/img/src/variable-label-placement.png b/docs/img/src/variable-label-placement.png
diff --git a/docs/img/src/vector-source.png b/docs/img/src/vector-source.png
diff --git a/docs/img/src/video-on-a-map.png b/docs/img/src/video-on-a-map.png
diff --git a/docs/img/src/visualize-population-density.png b/docs/img/src/visualize-population-density.png
diff --git a/docs/img/src/wms.png b/docs/img/src/wms.png
diff --git a/docs/img/src/zoomto-linestring.png b/docs/img/src/zoomto-linestring.png