diff --git a/docs/README.md b/docs/README.md index 9dffc7d7e01..ea6d3fc3eef 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,12 +35,10 @@ In the `.html` file, write the HTML and JavaScript constituting the example. Every example **must** have an accompanying image: -1. Save the image in `docs/img/src/`. Image requirements: - - The file name of the image **must** match the example's file name - - 1200 x 500 pixel - - png format -2. Run `npm run build-images` to generate the appropriate images. Alternatively, when you run `npm run start-docs` the site will generate the images. -3. Run the site locally to verify that your example image is loading as expected. +1. Run `npm run create-image `. 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 diff --git a/docs/bin/create-image.js b/docs/bin/create-image.js new file mode 100644 index 00000000000..d3e75c5f399 --- /dev/null +++ b/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 \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 = ` + + + + + + + + + +${snippet} + +`; + +// 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(); +})(); diff --git a/package.json b/package.json index 5cc022edb54..34b4a58593b 100644 --- a/package.json +++ b/package.json @@ -80,6 +80,7 @@ "pretty-bytes": "^5.1.0", "prismjs": "^1.15.0", "prop-types": "^15.6.2", + "puppeteer": "^1.13.0", "raw-loader": "^1.0.0", "react": "^16.7.0", "react-dom": "^16.7.0", @@ -129,6 +130,7 @@ "start-bench": "run-p build-token watch-benchmarks watch-style-benchmarks start-server", "build-docs": "documentation build --github --format json --config ./docs/documentation.yml --output docs/components/api.json src/index.js && npm run build-images", "build-images": "mkdir -p docs/img/dist && node docs/bin/build-image-config.js && node docs/bin/appropriate-images.js --all", + "create-image": "node docs/bin/create-image", "build": "run-s build-docs && batfish build # invoked by publisher when publishing docs on the publisher-production branch", "start-docs": "run-s build-prod-min build-css build-docs && DEPLOY_ENV=local batfish start", "lint": "eslint --cache --ignore-path .gitignore src test bench docs docs/pages/example/*.html debug/*.html", diff --git a/yarn.lock b/yarn.lock index 193255197d2..8060301424e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3828,7 +3828,7 @@ concat-map@0.0.1: version "0.0.1" resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b" -concat-stream@^1.4.6, concat-stream@^1.4.7, concat-stream@^1.5.1: +concat-stream@1.6.2, concat-stream@^1.4.6, concat-stream@^1.4.7, concat-stream@^1.5.1: version "1.6.2" resolved "https://registry.yarnpkg.com/concat-stream/-/concat-stream-1.6.2.tgz#904bdf194cd3122fc675c77fc4ac3d4ff0fd1a34" dependencies: @@ -5874,6 +5874,16 @@ extglob@^2.0.4: snapdragon "^0.8.1" to-regex "^3.0.1" +extract-zip@^1.6.6: + version "1.6.7" + resolved "https://registry.yarnpkg.com/extract-zip/-/extract-zip-1.6.7.tgz#a840b4b8af6403264c8db57f4f1a74333ef81fe9" + integrity sha1-qEC0uK9kAyZMjbV/Txp0Mz74H+k= + dependencies: + concat-stream "1.6.2" + debug "2.6.9" + mkdirp "0.5.1" + yauzl "2.4.1" + extsprintf@1.3.0: version "1.3.0" resolved "https://registry.yarnpkg.com/extsprintf/-/extsprintf-1.3.0.tgz#96918440e3041a7a414f8c52e3c574eb3c3e1e05" @@ -5940,6 +5950,13 @@ fbjs@^0.8.16: setimmediate "^1.0.5" ua-parser-js "^0.7.9" +fd-slicer@~1.0.1: + version "1.0.1" + resolved "https://registry.yarnpkg.com/fd-slicer/-/fd-slicer-1.0.1.tgz#8b5bcbd9ec327c5041bf9ab023fd6750f1177e65" + integrity sha1-i1vL2ewyfFBBv5qwI/1nUPEXfmU= + dependencies: + pend "~1.2.0" + fd-slicer@~1.1.0: version "1.1.0" resolved "https://registry.yarnpkg.com/fd-slicer/-/fd-slicer-1.1.0.tgz#25c7c89cb1f9077f8891bbe61d8f390eae256f1e" @@ -7333,7 +7350,7 @@ https-browserify@^1.0.0: version "1.0.0" resolved "https://registry.yarnpkg.com/https-browserify/-/https-browserify-1.0.0.tgz#ec06c10e0a34c0f2faf199f7fd7fc78fffd03c73" -https-proxy-agent@^2.2.0: +https-proxy-agent@^2.2.0, https-proxy-agent@^2.2.1: version "2.2.1" resolved "https://registry.yarnpkg.com/https-proxy-agent/-/https-proxy-agent-2.2.1.tgz#51552970fa04d723e04c56d04178c3f92592bbc0" dependencies: @@ -9176,14 +9193,14 @@ mime@1.4.1, mime@~1.4.1: version "1.4.1" resolved "https://registry.yarnpkg.com/mime/-/mime-1.4.1.tgz#121f9ebc49e3766f311a76e1fa1c8003c4b03aa6" +mime@^2.0.3, mime@^2.3.1: + version "2.4.0" + resolved "https://registry.yarnpkg.com/mime/-/mime-2.4.0.tgz#e051fd881358585f3279df333fe694da0bcffdd6" + mime@^2.2.0: version "2.3.1" resolved "https://registry.yarnpkg.com/mime/-/mime-2.3.1.tgz#b1621c54d63b97c47d3cfe7f7215f7d64517c369" -mime@^2.3.1: - version "2.4.0" - resolved "https://registry.yarnpkg.com/mime/-/mime-2.4.0.tgz#e051fd881358585f3279df333fe694da0bcffdd6" - mimic-fn@^1.0.0: version "1.2.0" resolved "https://registry.yarnpkg.com/mimic-fn/-/mimic-fn-1.2.0.tgz#820c86a39334640e99516928bd03fca88057d022" @@ -9294,7 +9311,7 @@ mixin-deep@^1.2.0: for-in "^1.0.2" is-extendable "^1.0.1" -"mkdirp@>=0.5 0", mkdirp@^0.5.0, mkdirp@^0.5.1, mkdirp@~0.5.0, mkdirp@~0.5.1: +mkdirp@0.5.1, "mkdirp@>=0.5 0", mkdirp@^0.5.0, mkdirp@^0.5.1, mkdirp@~0.5.0, mkdirp@~0.5.1: version "0.5.1" resolved "https://registry.yarnpkg.com/mkdirp/-/mkdirp-0.5.1.tgz#30057438eac6cf7f8c4767f38648d6697d75c903" dependencies: @@ -10875,6 +10892,11 @@ progress@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/progress/-/progress-2.0.0.tgz#8a1be366bf8fc23db2bd23f10c6fe920b4389d1f" +progress@^2.0.1: + version "2.0.3" + resolved "https://registry.yarnpkg.com/progress/-/progress-2.0.3.tgz#7e8cf8d8f5b8f239c1bc68beb4eb78567d572ef8" + integrity sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA== + promise-inflight@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/promise-inflight/-/promise-inflight-1.0.1.tgz#98472870bf228132fcbdd868129bad12c3c029e3" @@ -10934,6 +10956,11 @@ protocols@^1.1.0, protocols@^1.4.0: version "1.4.6" resolved "https://registry.yarnpkg.com/protocols/-/protocols-1.4.6.tgz#f8bb263ea1b5fd7a7604d26b8be39bd77678bf8a" +proxy-from-env@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/proxy-from-env/-/proxy-from-env-1.0.0.tgz#33c50398f70ea7eb96d21f7b817630a55791c7ee" + integrity sha1-M8UDmPcOp+uW0h97gXYwpVeRx+4= + prr@~1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/prr/-/prr-1.0.1.tgz#d3fc114ba06995a45ec6893f484ceb1d78f5f476" @@ -11012,6 +11039,20 @@ punycode@^2.1.0: version "2.1.0" resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.1.0.tgz#5f863edc89b96db09074bad7947bf09056ca4e7d" +puppeteer@^1.13.0: + version "1.13.0" + resolved "https://registry.yarnpkg.com/puppeteer/-/puppeteer-1.13.0.tgz#187ccf5ed5caf08ed1291b262d033cc364bf88ab" + integrity sha512-LUXgvhjfB/P6IOUDAKxOcbCz9ISwBLL9UpKghYrcBDwrOGx1m60y0iN2M64mdAUbT4+7oZM5DTxOW7equa2fxQ== + dependencies: + debug "^4.1.0" + extract-zip "^1.6.6" + https-proxy-agent "^2.2.1" + mime "^2.0.3" + progress "^2.0.1" + proxy-from-env "^1.0.0" + rimraf "^2.6.1" + ws "^6.1.0" + q@^1.1.2: version "1.5.1" resolved "https://registry.yarnpkg.com/q/-/q-1.5.1.tgz#7e32f75b41381291d04611f1bf14109ac00651d7" @@ -14895,6 +14936,13 @@ yargs@~3.10.0: decamelize "^1.0.0" window-size "0.1.0" +yauzl@2.4.1: + version "2.4.1" + resolved "https://registry.yarnpkg.com/yauzl/-/yauzl-2.4.1.tgz#9528f442dab1b2284e58b4379bb194e22e0c4005" + integrity sha1-lSj0QtqxsihOWLQ3m7GU4i4MQAU= + dependencies: + fd-slicer "~1.0.1" + yauzl@^2.2.1, yauzl@^2.4.2: version "2.10.0" resolved "https://registry.yarnpkg.com/yauzl/-/yauzl-2.10.0.tgz#c7eb17c93e112cb1086fa6d8e51fb0667b79a5f9"