Docusaurus documentation

.editorconfig

@@ -9,8 +9,8 @@ indent_style = space
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{js,html,css}]
+[*.{ts,html,css}]
 indent_size = 4
 
-[*.{json,yml}]
+[*.{js,json,yml}]
 indent_size = 2

.github/CONTRIBUTING.md

@@ -5,10 +5,12 @@ Thanks in advance for contributing to MapillaryJS. Please follow the conventions
 Facebook has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its Code of Conduct, and we expect project participants to adhere to it. Please read [the full text](.CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
 
 ## Contribution Prerequisites
-- You have [Node](https://nodejs.org) installed at v14.16.0+ and [Yarn](https://classic.yarnpkg.com) at v1.2.0+.
+
+- You have [Node](https://nodejs.org) installed at v16.1.0+ and [Yarn](https://classic.yarnpkg.com) at v1.2.0+.
 - You are familiar with [Git](https://git-scm.com/).
 
 ## Sending a Pull Request
+
 We will review your pull request and either merge it, request changes to it, or close it with an explanation. We’ll do our best to provide updates and feedback throughout the process.
 
 **Before submitting a pull request**, please make sure the following is done:
@@ -21,11 +23,13 @@ We will review your pull request and either merge it, request changes to it, or
 6. If you haven’t already, complete the CLA.
 
 ## Contributor License Agreement (CLA)
+
 In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you’ve done this for another Facebook open source project, you’re good to go. If you are submitting a pull request for the first time, just let us know that you have completed the CLA and we can cross-check with your GitHub username.
 
 [Complete your CLA here.](https://code.facebook.com/cla)
 
 ## Develop with Docker
+
 1. Install [Docker](https://www.docker.com/).
 2. Clone the repository.
 3. Build the mapillary-js image:
@@ -44,13 +48,15 @@ docker run -v "$(pwd)":/source/mapillary-js -p 8000:8000 --name mapillary-js-con
 5. [Stop](https://docs.docker.com/engine/reference/commandline/stop/), [start](https://docs.docker.com/engine/reference/commandline/start/), and [attach](https://docs.docker.com/engine/reference/commandline/exec/) to the container.
 
 ## Development Workflow
-After cloning MapillaryJS, run `yarn` to fetch its dependencies. Then, you can run several commands:
+
+After cloning MapillaryJS, run `yarn install` to fetch its dependencies. Then, you can run several commands:
 
 - `yarn lint` checks the code style.
 - `yarn test` runs the complete test suite.
 - `yarn test-watch` runs an interactive test watcher.
 - `yarn build` creates a `dist` folder with the package.
-- `yarn build-docs` builds the documentation in the `docs/build` folder.
+- `yarn start` starts a development server and rebuilds on source file changes.
+- `yarn clear` removes the build output.
 
 We recommend running `yarn test` to make sure you don’t introduce any regressions as you work on your change.
 
@@ -60,6 +66,17 @@ However it can be handy to try your build of MapillaryJS in a real project. Firs
 
 If you want to try your changes in your existing project, you may use `yarn link` or copy the `dist` folder into your app and use them instead of the stable version.
 
+## Documentation workflow
+
+After cloning MapillaryJS, run `yarn --cwd doc install` to fetch the documentation website generation dependencies. Then, you can run several commands:
+
+- `yarn --cwd doc ci` checks the code style.
+- `yarn --cwd doc build-api` builds the API reference in the `doc/api` folder spearately. Running this command is not needed for building the static documentation.
+- `yarn --cwd doc build` generates static documentation content in the `doc/build` folder.
+- `yarn --cwd doc serve` starts a local development server and serves the static build output.
+- `yarn --cwd doc start-docs` starts a local development, opens up a browser window, and rebuilds on file changes. It omits the API and examples sections for faster iteration.
+- `yarn --cwd doc clear` removes the doc build output.
+
 ## Commit conventions
 
 We use the standardized commit messages according to [Conventional Commits](https://conventionalcommits.org/) with the additional types in the Angular convention.

.github/workflows/yarn.yml

@@ -6,21 +6,35 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+      - uses: actions/checkout@v2
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v1
-      with:
-        node-version: '14.x'
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: "15.x"
 
-    - name: Install dependencies
-      run: yarn --frozen-lockfile
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --ignore-scripts
 
-    - name: Build
-      run: yarn prepare
+      - name: Lint
+        run: yarn lint
 
-    - name: Test
-      run: yarn test
+      - name: Build
+        run: yarn build
 
-    - name: Build documentation
-      run: yarn build-docs
+      - name: Test
+        run: yarn test
+
+      - name: Install doc dependencies
+        run: yarn --cwd doc install
+
+      - name: Lint doc
+        run: yarn --cwd doc ci
+
+      - name: Build API reference
+        run: |
+          yarn --cwd doc build-api && \
+          yarn --cwd doc clear-api
+
+      - name: Build doc
+        run: yarn --cwd doc build

.gitignore

@@ -1,20 +1,21 @@
 # IDE
-.idea/
-.vagrant/
-.vscode/
+.idea
+.vagrant
+.vscode
 vagrant.*
 Vagrantfile
 
-# Package
-node_modules/
-yarn-error.log
-yarn-debug.log
+# Dependencies
+/node_modules
 
-# Filetypes
+# Misc
 *.DS_STORE
 *.tgz
 
+yarn-error.log*
+yarn-debug.log*
+
 # Artifacts
-build/
-dist/
-docs/build/
+/build
+/dist
+/docs

README.md

@@ -4,29 +4,32 @@
 
 # MapillaryJS
 
-MapillaryJS is an interactive, customizable street imagery and semantic mapping visualization platform for the web. It takes texture, semantic 2D, and spatial 3D data and renders it using JavaScript and WebGL. It can be extended with custom data loaders, renderers, and camera controls.
+MapillaryJS is an interactive, customizable street imagery and semantic mapping visualization platform on the web. It takes spatial, semantic, and texture data and renders it using JavaScript and WebGL. It can be extended with custom data providers, 3D model rendering, camera controls, and interactivity.
 
 <a href="https://www.mapillary.com">
 <img width="100%" alt="Mapillary" src="https://user-images.githubusercontent.com/2492302/117429732-9dbe1e80-af27-11eb-9531-47ae4df50c65.png">
 </a>
 
 ## Installation and usage
 
-To get started with data from the [Mapillary](https://www.mapillary.com) platform, you need an [app token](). When [extending MapillaryJS]() to render your own data, no app token is needed.
+To start using MapillaryJS with data from the [Mapillary](https://www.mapillary.com) platform, you need an app token. When extending MapillaryJS to render your own data, no app token is needed.
 
 <details open>
   <summary><b><code>ES6 bundler</code></b></summary>
 
 Install the package via [Yarn](https://classic.yarnpkg.com) (or [npm](https://docs.npmjs.com/about-npm)).
 
 ```sh
-yarn install mapillary-js
+yarn add mapillary-js
 ```
 
 Use a CSS loader or include the CSS file in the `<head>` of your HTML file.
 
 ```html
-<link href='https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.css' rel='stylesheet' />
+<link
+  href="https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.css"
+  rel="stylesheet"
+/>
 ```
 
 Include the following code in your JavaScript file.
@@ -35,11 +38,12 @@ Include the following code in your JavaScript file.
 import { Viewer } from "mapillary-js";
 
 const viewer = new Viewer({
-    apiClient: '<your app token>',
-    container: '<your HTML element ID>',
-    imageId: '<your image ID for initializing the viewer>',
+  apiClient: "<your app token>",
+  container: "<your HTML element ID>",
+  imageId: "<your image ID for initializing the viewer>",
 });
 ```
+
 </details>
 
 <details>
@@ -48,13 +52,16 @@ const viewer = new Viewer({
 Install the package via [Yarn](https://classic.yarnpkg.com) (or [npm](https://docs.npmjs.com/about-npm)).
 
 ```sh
-yarn install mapillary-js
+yarn add mapillary-js
 ```
 
 Use a CSS loader or include the CSS file in the `<head>` of your HTML file.
 
 ```html
-<link href='https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.css' rel='stylesheet' />
+<link
+  href="https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.css"
+  rel="stylesheet"
+/>
 ```
 
 Include the following code in your TypeScript file.
@@ -63,23 +70,26 @@ Include the following code in your TypeScript file.
 import { Viewer, ViewerOptions } from "mapillary-js";
 
 const options: ViewerOptions = {
-    apiClient: '<your app token>',
-    container: '<your HTML element ID>',
-    imageId: '<your image ID for initializing the viewer>',
+  apiClient: "<your app token>",
+  container: "<your HTML element ID>",
+  imageId: "<your image ID for initializing the viewer>",
 };
 const viewer = new Viewer(options);
 ```
+
 </details>
 
 <details>
   <summary><b><code>CDN</code></b></summary>
 
-
 Include the JavaScript and CSS files in the `<head>` of your HTML file.
 
 ```html
-<script src='https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.js'></script>
-<link href='https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.css' rel='stylesheet' />
+<script src="https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.js"></script>
+<link
+  href="https://unpkg.com/mapillary-js@4.0.0/dist/mapillary.css"
+  rel="stylesheet"
+/>
 ```
 
 The global [UMD](https://github.com/umdjs/umd) namespace for MapillaryJS is `mapillary`. Include the following code in your JavaScript file.
@@ -88,25 +98,26 @@ The global [UMD](https://github.com/umdjs/umd) namespace for MapillaryJS is `map
 var { Viewer } = mapillary;
 
 var viewer = new Viewer({
-    apiClient: '<your app token>',
-    container: '<your HTML element ID>',
-    imageId: '<your image ID for initializing the viewer>',
+  apiClient: "<your app token>",
+  container: "<your HTML element ID>",
+  imageId: "<your image ID for initializing the viewer>",
 });
 ```
+
 </details>
 
 ## Documentation
 
-- [Getting started with MapillaryJS]()
-- [Developing extensions]()
-- [Examples]()
+- Getting started with MapillaryJS
+- Developing extensions
+- Examples
 - [API reference](https://mapillary.github.io/mapillary-js)
 - [Migration guide](./MIGRATING.md)
 - [Contributor documentation](./.github/CONTRIBUTING.md)
 
 ## Code of Conduct
 
-Facebook has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its [Code of Conduct](https://code.facebook.com/codeofconduc), and we expect project participants to adhere to it. Please read [the full text](./.github/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
+Facebook has adopted the [Contributor Covenant](https://www.contributor-covenant.org/) as its [Code of Conduct](https://code.facebook.com/codeofconduct), and we expect project participants to adhere to it. Please read [the full text](./.github/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
 
 ## License
 

doc/.eslintignore

@@ -0,0 +1,7 @@
+# Dependencies
+node_modules
+
+# Generated files
+.docusaurus
+api
+build

doc/.eslintrc.js

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+const OFF = 0;
+const ERROR = 2;
+
+module.exports = {
+  root: true,
+  env: {
+    browser: true,
+    commonjs: true,
+    jest: true,
+    node: true,
+  },
+  parser: '@babel/eslint-parser',
+  parserOptions: {
+    allowImportExportEverywhere: true,
+  },
+  extends: ['airbnb', 'prettier', 'prettier/react'],
+  plugins: ['react-hooks', 'header'],
+  rules: {
+    // Ignore certain webpack alias because it can't be resolved
+    'import/no-unresolved': [
+      ERROR,
+      {ignore: ['^@theme', '^@docusaurus', '^@generated']},
+    ],
+    'import/extensions': OFF,
+    'header/header': [
+      ERROR,
+      'block',
+      [
+        '*',
+        ' * Copyright (c) Facebook, Inc. and its affiliates.',
+        ' *',
+        ' * This source code is licensed under the MIT license found in the',
+        ' * LICENSE file in the root directory of this source tree.',
+        ' *',
+        // Unfortunately eslint-plugin-header doesn't support optional lines.
+        // If you want to enforce your website JS files to have @flow or @format,
+        // modify these lines accordingly.
+        {
+          pattern: '.* @format',
+        },
+        ' ',
+      ],
+    ],
+    'react/jsx-closing-bracket-location': OFF, // Conflicts with Prettier.
+    'react/jsx-filename-extension': OFF,
+    'react-hooks/rules-of-hooks': ERROR,
+    'react/prop-types': OFF, // PropTypes aren't used much these days.
+    'no-console': ['error', {allow: ['warn', 'error']}],
+  },
+};