Initial commit to bring in the docs

.gitignore

@@ -3,6 +3,8 @@
 /dist/
 /dist_type/
 /test/bench/results/
+/docs/API
+/docs/examples
 *.es.js
 *.js.map
 node_modules

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### ✨ Features and improvements
 
 - Change all internal exports to named exports([#2711](https://github.com/maplibre/maplibre-gl-js/pull/2711))
+- Docs generation is now part of this repo([#2733](https://github.com/maplibre/maplibre-gl-js/pull/2733))
 - Add `className` option to Marker constructor ([#2729](https://github.com/maplibre/maplibre-gl-js/pull/2729))
 - _...Add new stuff here..._
 

build/generate-doc-images.ts

@@ -0,0 +1,73 @@
+import path from 'path';
+import fs from 'fs';
+import puppeteer from 'puppeteer';
+import packageJson from '../package.json' assert { type: 'json' };
+
+const exampleName = process.argv[2];
+const examplePath = path.resolve('test', 'examples');
+
+const browser = await puppeteer.launch({headless: exampleName === 'all'});
+
+const page = await browser.newPage();
+// set viewport and double deviceScaleFactor to get a closer shot of the map
+await page.setViewport({
+    width: 600,
+    height: 250,
+    deviceScaleFactor: 2
+});
+
+async function createImage(exampleName) {
+    // get the example contents
+    const html = fs.readFileSync(path.resolve(examplePath, `${exampleName}.html`), 'utf-8');
+
+    await page.setContent(html.replaceAll('../../dist', `https://unpkg.com/maplibre-gl@${packageJson.version}/dist`));
+
+    // 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;
+            await new Promise((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/assets/examples/${exampleName}.png`,
+            type: 'png',
+            clip: {
+                x: 0,
+                y: 0,
+                width: 600,
+                height: 250
+            }
+        })
+        .then(() => console.log(`Created ./docs/assets/examples/${exampleName}.png`))
+        .catch((err) => {
+            console.log(err);
+        });
+}
+
+if (exampleName === 'all') {
+    const allFiles = fs.readdirSync(examplePath).filter(f => f.endsWith('html'));
+    console.log(`Generating ${allFiles.length} images.`);
+    for (const file of allFiles) {
+        await createImage(file);
+    }
+} else if (exampleName) {
+    await createImage(exampleName);
+} else {
+    throw new Error(
+        '\n  Usage: npm run generate-images <file-name|all>\nExample: npm run generate-images 3d-buildings'
+    );
+}
+
+await browser.close();

build/generate-docs.ts

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import typedocConfig from '../typedoc.json' assert {type: 'json'};
+import packageJson from '../package.json' assert {type: 'json'};
+
+type HtmlDoc = {
+    title: string;
+    description: string;
+    mdFileName: string;
+}
+
+function generateAPIIntroMarkdown(lines: string[]): string {
+    let intro = `# Intro
+
+This file is intended as a reference for the important and public classes of this API.
+
+We reccomend to look at the [expamples](../examples/index.md) as they will help you the most to start with MapLibre.
+`;
+    intro += lines.map(l => l.replace('../', './')).join('\n');
+    return intro;
+}
+
+function generateMarkdownForExample(title: string, description: string, file: string, htmlContent: string): string {
+    return `
+# ${title}
+
+${description}
+
+<iframe src="../${file}" width="100%" style="border:none; height:400px"></iframe>
+
+\`\`\`html
+${htmlContent}
+\`\`\`
+`;
+}
+
+function generateMarkdownIndexFileOfAllExamples(indexArray: HtmlDoc[]): string {
+    let indexMarkdown = '# Exmaples \n\n';
+    for (const indexArrayItem of indexArray) {
+        indexMarkdown += `
+## [${indexArrayItem.title}](./${indexArrayItem.mdFileName})
+
+![${indexArrayItem.description}](../assets/examples/${indexArrayItem.mdFileName!.replace('.md', '.png')})
+
+${indexArrayItem.description}
+`;
+    }
+    return indexMarkdown;
+}
+
+if (!fs.existsSync(typedocConfig.out)) {
+    throw new Error('Please run typedoc generation first!');
+}
+
+fs.rmSync(path.join(typedocConfig.out, 'README.md'));
+fs.rmSync(path.join(typedocConfig.out, 'modules.md'));
+// Intro file for the API
+const modulesFolder = path.join(typedocConfig.out, 'modules');
+const content = fs.readFileSync(path.join(modulesFolder, `${typedocConfig.internalModule}.md`), 'utf-8');
+let lines = content.split('\n');
+const classesLineIndex = lines.indexOf(lines.find(l => l.endsWith('Classes')) as string);
+lines = lines.splice(2, classesLineIndex - 2);
+const contentString = generateAPIIntroMarkdown(lines);
+fs.writeFileSync(path.join(typedocConfig.out, 'README.md'), contentString);
+
+// Examples manupilation
+const examplesDocsFolder = path.join('docs', 'examples');
+if (fs.existsSync(examplesDocsFolder)) {
+    fs.rmSync(examplesDocsFolder, {recursive: true, force: true});
+}
+fs.mkdirSync(examplesDocsFolder);
+const examplesFolder = path.join('test', 'examples');
+const files = fs.readdirSync(examplesFolder).filter(f => f.endsWith('html'));
+const maplibreUnpgk = `https://unpkg.com/maplibre-gl@${packageJson.version}/`;
+const indexArray = [] as HtmlDoc[];
+for (const file of files) {
+    const htmlFile = path.join(examplesFolder, file);
+    let htmlContent = fs.readFileSync(htmlFile, 'utf-8');
+    htmlContent = htmlContent.replace(/\.\.\/\.\.\//g, maplibreUnpgk);
+    htmlContent = htmlContent.replace(/-dev.js/g, '.js');
+    const htmlContentLines = htmlContent.split('\n');
+    const title = htmlContentLines.find(l => l.includes('<title'))?.replace('<title>', '').replace('</title>', '').trim();
+    const description = htmlContentLines.find(l => l.includes('og:description'))?.replace(/.*content=\"(.*)\".*/, '$1');
+    fs.writeFileSync(path.join(examplesDocsFolder, file), htmlContent);
+    const mdFileName = file.replace('.html', '.md');
+    indexArray.push({
+        title: title!,
+        description: description!,
+        mdFileName
+    });
+    const exampleMarkdown = generateMarkdownForExample(title, description, file, htmlContent);
+    fs.writeFileSync(path.join(examplesDocsFolder, mdFileName), exampleMarkdown);
+}
+
+const indexMarkdown = generateMarkdownIndexFileOfAllExamples(indexArray);
+fs.writeFileSync(path.join(examplesDocsFolder, 'index.md'), indexMarkdown);
+
+console.log('Docs generation completed, to see it in action run\n docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material');

docs/README.md

@@ -0,0 +1,84 @@
+# Introduction
+
+MapLibre GL JS is a TypeScript library that uses WebGL2 to render interactive maps from vector tiles in a browser. The customization of the map comply with the [MapLibre Style Spec](https://maplibre.org/maplibre-style-spec). It is part of the [MapLibre ecosystem](https://github.com/maplibre), with a pendant for Mobile, Desktop, Servers called [MapLibre Native](https://maplibre.org/projects/maplibre-native/).
+
+
+## Quickstart
+
+<iframe src="./examples/simple-map.html" width="100%" style="border:none"></iframe>
+
+```html
+<div id="map"></div>
+<script>
+    var map = new maplibregl.Map({
+        container: 'map', // container id
+        style: 'https://demotiles.maplibre.org/style.json', // style URL
+        center: [0, 0], // starting position [lng, lat]
+        zoom: 1 // starting zoom
+    });
+</script>
+```
+
+
+## Reading this documentation
+
+This documentation is divided into several sections:
+
+* [**Map**](https://maplibre.org/maplibre-gl-js-docs/api/map/). The `Map` object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
+* [**Properties and options**](https://maplibre.org/maplibre-gl-js-docs/api/properties/). This section describes MapLibre GL JS's global properties and options that you might want to access while initializing your map or accessing information about its status.
+* [**Markers and controls**](https://maplibre.org/maplibre-gl-js-docs/api/markers/). This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's `canvas` element.
+* [**Geography and geometry**](https://maplibre.org/maplibre-gl-js-docs/api/geography/). This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.
+* [**User interaction handlers**](https://maplibre.org/maplibre-gl-js-docs/api/handlers/). The items in this section relate to the ways in which the map responds to user input.
+* [**Sources**](https://maplibre.org/maplibre-gl-js-docs/api/sources/). This section describes the source types MapLibre GL JS can handle besides the ones described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
+* [**Events**](https://maplibre.org/maplibre-gl-js-docs/api/events/). This section describes the different types of events that MapLibre GL JS can raise.
+
+Each section describes classes or objects as well as their **properties**, **parameters**, **instance members**, and associated **events**. Many sections also include inline code examples and related resources.
+
+In the examples, we use vector tiles from [MapTiler](https://maptiler.com). Get your own API key if you want to use MapTiler data in your project.
+
+## CSP Directives
+
+As a mitigation for Cross-Site Scripting and other types of web security vulnerabilities, you may use a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/Security/CSP) to specify security policies for your website. If you do, MapLibre GL JS requires the following CSP directives:
+
+```
+worker-src blob: ;
+child-src blob: ;
+img-src data: blob: ;
+```
+
+Requesting styles from Mapbox or other services will require additional directives. For Mapbox, you can use this `connect-src` directive:
+
+```
+connect-src https://*.tiles.mapbox.com https://api.mapbox.com https://events.mapbox.com
+```
+
+For strict CSP environments without `worker-src blob: ; child-src blob:` enabled, there's a separate MapLibre GL JS bundle (`maplibre-gl-csp.js` and `maplibre-gl-csp-worker.js`) which requires setting the path to the worker manually:
+
+
+```html
+<script>
+maplibregl.workerUrl = "${urls.js().replace('.js', '-csp-worker.js')}";
+...
+</script>
+```
+
+## MapLibre CSS
+
+The CSS referenced in the Quickstart is used to style DOM elements created by MapLibre code. Without the CSS, elements like Popups and Markers won't work.
+
+Including it with a `<link>` in the head of the document via the UNPKG CDN is the simplest and easiest way to provide the CSS, but it is also bundled in the MapLibre module, meaning that if you have a bundler that can handle CSS, you can import the CSS from `maplibre-gl/dist/maplibre-gl.css`.
+
+Note too that if the CSS isn't available by the first render, as soon as the CSS is provided, the DOM elements that depend on this CSS should recover.
+
+## Dependencies
+
+The dependencies for MapLibre GL JS (`.js` & `.css`) are distributed via [UNPKG.com](https://unpkg.com).  UNPKG can distribute a fixed version, a [semver range](https://semver.org/), a tag, or omit the version/tag entirely to use the `latest` tag.
+
+You can view a listing of all the files in the MapLibre GL JS package by appending a `/` at the end of the MapLibre slug.  This is useful to review other revisions or to review the files at UNPKG or the LICENSE.  See <https://unpkg.com/maplibre-gl/>
+
+*Examples*
+
+| Use Case  | `.js` | `.css` |
+| :------- | :---: | :----: |
+| `latest` |`https://unpkg.com/maplibre-gl/dist/maplibre-gl.js` | `https://unpkg.com/maplibre-gl/dist/maplibre-gl.css` |
+| Use at least `2.4.x` | <https://unpkg.com/maplibre-gl@^2.4/dist/maplibre-gl.js> | <https://unpkg.com/maplibre-gl@^2.4/dist/maplibre-gl.css> |