Merge branch 'publisher-production' into sync-publisher-production

* publisher-production: (41 commits)
  bump publisher after timeout (#8058)
  cosmetic update to draggable Marker/point examples to prevent coordinates overlapping Mapbox logo (#8057)
  update mapbox style and tileset version numbers to most recent (#8056)
  update docs page shell (#8039)
  [email protected]
  Add create-image script to generate example thumbnails (#8029)
  Add HTML clusters + aggregated properties example (#8019)
  add 3D model with three.js example (#7977)
  update mapbox-gl-geocoder to @3.1.4 in examples (#7978)
  V0.53.1 (#7961)
  rename example for accepting coordinates in the geocoder (#7859)
  [docs] use appropriate-images for examples to increase page speed (#7900)
  [docs] dr-ui 0.6.0 (#7909)
  version bump gl-geocoder to v3.1.2 (#7924)
  Fix docs for Camera methods
  Docs page shell update 02-14-19 (#7907)
  fixes regression with css on examples pages (#7891)
  updates sentry project for docs subdomain (#7890)
  v0.53.0 (#7884)
  [docs] update dr-ui 0.5.0 (#7880)
  ...

.gitignore

@@ -2,6 +2,7 @@
 /docs/components/api.json
 /dist/
 /docs/pages/dist/
+/docs/img/dist/
 *.js.map
 node_modules
 package-lock.json

batfish.config.js

@@ -1,4 +1,5 @@
-const { webpack } = require('@mapbox/batfish');
+const webpack = require('webpack');
+const mapboxAssembly = require('@mapbox/mbx-assembly');
 const path = require('path');
 
 module.exports = () => {
@@ -7,9 +8,13 @@ module.exports = () => {
         siteOrigin: 'https://docs.mapbox.com',
         pagesDirectory: `${__dirname}/docs/pages`,
         outputDirectory: path.join(__dirname, '_site'),
+        browserslist: mapboxAssembly.browsersList,
+        postcssPlugins: mapboxAssembly.postcssPipeline.plugins,
         stylesheets: [
+            require.resolve('@mapbox/mbx-assembly/dist/assembly.css'),
+            require.resolve('@mapbox/dr-ui/css/docs-prose.css'),
             `${__dirname}/docs/components/site.css`,
-            `${__dirname}/docs/components/prism_highlight.css`,
+            require.resolve('@mapbox/dr-ui/css/prism.css'),
             `${__dirname}/vendor/docs-page-shell/page-shell-styles.css`
         ],
         applicationWrapperPath: `${__dirname}/docs/components/application-wrapper.js`,
@@ -33,14 +38,40 @@ module.exports = () => {
                 filename: `${__dirname}/vendor/docs-page-shell/page-shell-script.js`
             }
         ],
+        jsxtremeMarkdownOptions: {
+            wrapper: path.join(__dirname, './docs/components/markdown-page-shell.js'),
+            rehypePlugins: [
+                require('@mapbox/dr-ui/plugins/add-links-to-headings'),
+                require('@mapbox/dr-ui/plugins/make-table-scroll')
+            ]
+        },
         dataSelectors: {
             examples: ({pages}) => {
                 return pages
                     .filter(({path, frontMatter}) => /\/example\//.test(path) && frontMatter.tags)
-                    .map(({frontMatter}) => frontMatter);
+                    .map(example => {
+                        return {
+                            path: example.path,
+                            title: example.frontMatter.title,
+                            description: example.frontMatter.description,
+                            tags: example.frontMatter.tags,
+                            pathname: example.frontMatter.pathname
+                        };
+                    });
+            },
+            listSubfolders: data => {
+                const folders = data.pages
+                    .filter(file => {
+                        return file.path.split('/').length === 4;
+                    })
+                    .map(folder => {
+                        return folder;
+                    });
+                return folders;
             }
         },
-        devBrowserslist: false
+        devBrowserslist: false,
+        babelInclude: ['documentation']
     };
 
     // Local builds treat the `dist` directory as static assets, allowing you to test examples against the

docs/README.md

@@ -23,7 +23,7 @@ code for the example, and a `.js` file containing example boilerplate and front
 
 * `title`: A short title for the example in **sentence case** as a **verb phrase**
 * `description`: A one sentence description of the example
-* `tags`: An array of tags for the example, which determine the sections it is listed in in the sidebar navigation
+* `tags`: An array of tags for the example, which determine the sections it is listed in in the sidebar navigation, see `docs/data/tags.js` for a list of tags
 * `pathname`: The relative path of the example, including leading `/mapbox-gl-js/example/` path
 
 In the `.html` file, write the HTML and JavaScript constituting the example.
@@ -33,6 +33,13 @@ In the `.html` file, write the HTML and JavaScript constituting the example.
 * Do **not** use custom styles from your personal account. Use only the default `mapbox` account styles.
 * When embedding literal JSON (GeoJSON or Mapbox style snippets) into script code, double-quote property names and string values. Elsewhere, use single-quoted strings.
 
+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 run start-docs` 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 run start-docs` 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.
+
 ## Running the Documentation Server Locally
 
 To start a documentation server locally run
@@ -42,6 +49,8 @@ npm run start-docs
 
 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 8 && npm run start-docs`.
+
 ## Committing and Publishing Documentation
 
 The mapbox-gl-js repository has both `master` and `publisher-production` as active branches. The **`master` branch** is used for mainline code development: the next version of mapbox-gl-js will come from the code in this branch, and it may contain documentation and examples for APIs that are not yet part of a public release. The **`publisher-production` branch** is published to https://www.mapbox.com/mapbox-gl-js/ on any push to the branch. For the purposes of documentation changes, use these two branches as follows:

docs/bin/appropriate-images.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path'); // eslint-disable-line import/no-commonjs
+const appropriateImages = require('@mapbox/appropriate-images'); // eslint-disable-line import/no-commonjs
+const imageConfig = require('../img/dist/image.config.json'); // eslint-disable-line import/no-commonjs
+
+appropriateImages.createCli(imageConfig, {
+    inputDirectory: path.join(__dirname, '../img/src'),
+    outputDirectory: path.join(__dirname, '../img/dist')
+});

docs/bin/build-image-config.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// builds image.config.json
+// this configuration file is required to generate the appropriate images sizes with docs/bin/appropriate-images.js
+// it is also required in react component that loads the image in components/appropriate-image.js
+const imagePath = './docs/img/src/';
+
+const imageConfig = require('fs').readdirSync(imagePath).reduce((obj, image) => {
+    const ext = require('path').extname(`${imagePath}${image}`);
+    // only process png
+    if (ext === '.png') {
+        const key = image.replace(ext, '');
+        // set sizes for all images
+        const sizes = [{ width: 800 }, { width: 500 }];
+        // set additional sizes for specific images
+        if (key === 'simple-map') sizes.push({ width: 1200 });
+        obj[key] = {
+            basename: image,
+            sizes
+        };
+    }
+    return obj;
+}, {});
+
+require('fs').writeFileSync('./docs/img/dist/image.config.json', JSON.stringify(imageConfig));

docs/bin/create-image.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const puppeteer = require('puppeteer'); // eslint-disable-line
+const path = require('path'); // eslint-disable-line
+const pack = require('../../package.json'); // eslint-disable-line
+
+const fileName = process.argv[2];
+const token = process.argv[3] || process.env.MAPBOX_ACCESS_TOKEN || process.env.MapboxAccessToken;
+
+if (!token || !fileName) {
+    throw new Error('\n  Usage: npm run create-image <file-name> <mapbox-access-token>\nExample: npm run create-image 3d-buildings pk000011110000111100001111\n\n');
+}
+
+// strip file extension from file name
+const fileNameFormatted = fileName.replace('.html', '').replace('.js', '');
+// get the example contents/snippet
+const snippet = require('fs').readFileSync(path.resolve(__dirname, '..', 'pages', 'example', `${fileNameFormatted}.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://api.tiles.mapbox.com/mapbox-gl-js/v${pack.version}/mapbox-gl.js'></script>
+<link href='https://api.tiles.mapbox.com/mapbox-gl-js/v${pack.version}/mapbox-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>
+<script>
+mapboxgl.accessToken = '${token}';
+</script>
+${snippet}
+</body>
+</html>`;
+
+// initilize puppeteer
+(async() => {
+    const browser = await puppeteer.launch();
+    const page = await browser.newPage();
+    // set html for page and then wait until mapbox-gl-js loads
+    await page.setContent(html, {waitUntil: 'networkidle2'});
+    // set viewport and double deviceScaleFactor to get a closer shot of the map
+    await page.setViewport({
+        width: 600,
+        height: 600,
+        deviceScaleFactor: 2
+    });
+    // create screenshot
+    await page.screenshot({
+        path: `./docs/img/src/${fileNameFormatted}.png`,
+        type: 'png',
+        clip: {
+            x: 0,
+            y: 0,
+            width: 600,
+            height: 250
+        }
+    }).then(() => console.log(`Created ./docs/img/src/${fileNameFormatted}.png`))
+        .catch((err) => { console.log(err); });
+    await browser.close();
+})();

docs/components/api-item-member.js

@@ -0,0 +1,76 @@
+import React from 'react';
+import GithubSlugger from 'github-slugger';
+import createFormatters from 'documentation/src/output/util/formatters';
+import LinkerStack from 'documentation/src/output/util/linker_stack';
+import docs from '../components/api.json'; // eslint-disable-line import/no-unresolved
+import ApiItem from '../components/api-item';
+import Icon from '@mapbox/mr-ui/icon';
+
+const linkerStack = new LinkerStack({})
+    .namespaceResolver(docs, (namespace) => {
+        const slugger = new GithubSlugger();
+        return `#${slugger.slug(namespace)}`;
+    });
+
+const formatters = createFormatters(linkerStack.link);
+
+class ApiItemMember extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = {disclosed: false};
+        this.hashChange = this.hashChange.bind(this);
+    }
+
+    href = m => `#${m.namespace.toLowerCase()}`
+
+    render() {
+        const member = this.props;
+        return (
+            <div className='border-b border--gray-light'>
+                <div className='pt60' style={{ marginTop: '-60px' }} id={member.namespace.toLowerCase()} />
+                <div>
+                    <button
+                        className='cursor-pointer toggle-sibling color-blue-on-hover w-full py18'
+                        onClick={(e) => {
+                            this.setState({disclosed: !this.state.disclosed});
+                            if (history.pushState) {
+                                history.pushState(null, null, this.href(member));
+                            } else {
+                                location.hash = this.href(member);
+                            }
+
+                            e.preventDefault();
+                        }}
+                    >
+                        <span className='txt-code truncate bg-white'>{member.name}</span>
+                        {member.kind === 'function' &&
+                            <span className='color-gray txt-code mr12' dangerouslySetInnerHTML={{__html: formatters.parameters(member, true)}}/>}
+                        <div className='fr'><Icon size={30} name={`${this.state.disclosed ? 'caret-down' : 'caret-right'}`}  inline={true} /></div>
+                    </button>
+                </div>
+
+                {this.state.disclosed &&
+                    <div className="toggle-target bg-gray-faint round py18 px18 mb12">
+                        <ApiItem nested={true} {...member}/>
+                    </div>}
+            </div>
+        );
+    }
+
+    hashChange() {
+        if (window.location.hash === this.href(this.props)) {
+            this.setState({disclosed: true });
+        }
+    }
+
+    componentDidMount() {
+        window.addEventListener("hashchange", this.hashChange);
+        this.hashChange();
+    }
+
+    componentWillUnmount() {
+        window.removeEventListener("hashchange", this.hashChange);
+    }
+}
+
+export default ApiItemMember;