Doc fixes (visgl#511)

* Various doc fixes * Update Node version requirement.
mpearson · Mar 30, 2017 · b946fa2 · b946fa2
1 parent e41ff55
commit b946fa2
Show file tree

Hide file tree

Showing 7 changed files with 149 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -70,9 +70,10 @@ You will need to install dependencies in that example first:
 
 #### Node Version Requirement
 
-Building deck.gl from source has a dependency on node `4.0` or higher.
-Either upgrade to a newest version, or install something like
-[nvm](https://github.com/creationix/nvm).
+Running deck.gl as a dependency in another project (e.g. via `npm i deck.gl`) requires Node `v4` or higher.
+Building deck.gl from source has a dependency on Node `v6.4` or higher.
+Either upgrade to a supported version, or install something like
+[nvm](https://github.com/creationix/nvm) to manage Node versions.
 
 #### Install yarn
 On macOS deck.gl uses [yarn](https://www.npmjs.com/package/yarn) to manage packages.

diff --git a/docs/coordinate-systems.md b/docs/coordinate-systems.md
@@ -41,8 +41,6 @@ any 3D library.
 The application needs to manage the extents of positions in its data,
 and adjust view matrices accordingly.
 
-To use this mode.
-
 
 ## Support for the Web Mercator Projection and Cartographic Coordinate Systems
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -31,36 +31,24 @@ Remarks:
 
 ## Examples
 
-* The source code tabs in the Examples page in the interactive documentation
-* The deck.gl repository contains an
-  [examples folder](https://github.com/uber/deck.gl/tree/master/examples)
-  with a selection of standalone examples.
-  These foldiers can be copied and you should be able to get them running
-  simply by installing (`yarn` or `npm install` and running `npm start`).
+The deck.gl repository contains an
+[examples folder](https://github.com/uber/deck.gl/tree/master/examples)
+with a selection of small, standalone examples that could be good starting
+points for your application.
 
-There's also the [react-map-gl](https://github.com/uber/react-map-gl) exhibits folder. Although not integrating deck.gl, it will give you additional examples
-about how to use the base map component.
+These foldiers can be copied and you should be able to get them running
+simply by installing (`yarn` or `npm install` and running `npm start`).
 
+For more on using maps with deck.gl,it might also be worth checking out the
+[react-map-gl](https://github.com/uber/react-map-gl)
+examples. Although not focused on deck.gl, these will provide you with
+additional examples of how to use the base map component.
 
-## Note on "Map Tokens"
 
-This concerns Mapbox Tokens/Google Map Keys.
+## Note on Map Tokens
 
-Your main requirement before running any example will be to provide a map
-token to the examples so that they can load maps from mapbox/google etc.
+The main requirement before running any application using maps will be to provide
+a map token to the examples so that they can load maps from mapbox etc.
 
-To get a token, you typically need to register (create an account)
-with the map data provider, and apply for a token. The token will usually
-be free until a certain level of traffic is exceeded.
-
-There are several ways to provide a token:
-* Modify [app](./app.js) file to specify your Mapbox token,
-* Set an environment variable (MapboxAccessToken)
-* TBD - Provide the token in the URL
-
-Remarks:
-* If you fail to provide a token, the examples will still run,
-  and render any deck.gl overlays, but the underlying maps will not render.
-* The map token requirement obviously only applies only to examples that use
-  base maps, e.g. any examples using
-  [react-map-gl](https://github.com/uber/react-map-gl) to render map tiles.
+For more information about map token read the sections about "Using with Mapbox",
+and the [examples](https://github.com/uber/deck.gl/tree/master/examples/README.md)
diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
@@ -2,17 +2,20 @@
 
 ## Upgrading from deck.gl v3 to v4
 
-### Importing deck.gl React component
+### Changed Import: The `DeckGL` React component
 
-A small but breaking change is that the 'deck.gl/react' import is no
-longer available (see remarks). As of v4.0, the user is expected to
-import deck.gl using "pre-v3.0" way as follows:
+A small but breaking change that will affect all applications is that the
+'deck.gl/react' import is no longer available. As of v4.0, the app is required
+to import deck.gl as follows:
 ```
 // V4
 import DeckGL from 'deck.gl';
 // V3
 import DeckGL from 'deck.gl/react';
 ```
+While it would have been preferable to avoid this change, a significant
+modernization of the deck.gl build process and preparations for "tree-shaking"
+support combined to make it impractical to keep supporting the old import style.
 
 ### Removed, Changed and Deprecated Layer Properties
 
@@ -29,12 +32,6 @@ import DeckGL from 'deck.gl/react';
 This prop has been removed in deck.gl v4. Note that it was not functioning
 as documented in deck.gl v3.
 
-#### Removed lifecycle method: `Layer.willReceiveProps`
-
-This lifecycle was deprecated in v3 and is now removed. Use `Layer.updateState`
-instead.
-
-
 #### Renamed Props: The `...Scale` suffix
 
 Props that have their name end of `Scale` is a set of props that
@@ -45,6 +42,10 @@ values of specific attributes simultaneously.
 For API consistency reasons these have all been renamed with the suffix `..Scale`.
 See the property table above.
 
+#### Removed lifecycle method: `Layer.willReceiveProps`
+
+This lifecycle was deprecated in v3 and is now removed in v4.
+Use `Layer.updateState` instead.
 
 #### updateTriggers
 
@@ -65,8 +66,8 @@ loggers for all AttributeManagers (i.e. for all layers).
 
 #### Removed method: `AttributeManager.addDynamic`
 
-This method has been deprecated since version 2.5 and is now removed, use
-`AttributeManager.add()` instead
+This method has been deprecated since version 2.5 and is now removed in v4.
+Use `AttributeManager.add()` instead.
 
 
 ### Deprecated/Removed Layers
@@ -85,9 +86,9 @@ completely substituted by more unified, flexible and performant new layers:
  `GeoJsonLayer`, `PolygonLayer` and `PathLayer`.
 
 Developers should be able to just supply the same geojson data that are used with
- `ChoroplethLayer`s to the new `GeoJsonLayer`. The props of the `GeoJsonLayer` is
- also a bit different from the old `ChoroplethLayer`, so proper testing is recommended
- to achieve satisfactory result.
+`ChoroplethLayer`s to the new `GeoJsonLayer`. The props of the `GeoJsonLayer` are
+a bit different from the old `ChoroplethLayer`, so proper testing is recommended
+to achieve satisfactory result.
 
 As a deprecated layer, the Choropleth-family layers will stick around for
 at least another major revision, but please take some time to upgrade to the new

diff --git a/docs/using-with-mapbox-gl.md b/docs/using-with-mapbox-gl.md
@@ -7,11 +7,29 @@ the [react-map-gl](https://uber.github.io/react-map-gl/#/) component,
 which is a React wrapper around mapbox-gl, and is the recommended companion
 to use deck.gl for most applications.
 
-
 ## About react-map-gl
 
 As shown in the examples, the `DeckGL` React component works especially
 well as the child of a React component such as react-map-gl that displays
 a map using parameters similar to the deck.gl Viewport (i.e. latitude,
 longitude, zoom etc). In this configuration your deck.gl layers will
 render as a perfectly synchronized geospatial overlay over the underlying map.
+
+## About Mapbox Tokens
+
+To show maps from a service such as Mapbox you will need to register with
+Mapbox and get a "token" that you need to provide to your map component.
+The map component will use the token to identify itself to the mapbox service
+which then will start serving up map tiles.
+
+To get a token, you typically need to register (create an account)
+with the map data provider (mapbox), and apply for a token.
+The token will usually be free until a certain level of traffic is exceeded.
+
+While the token will need to be hard-coded into your application in
+production, there are several ways to provide a token during development:
+* Modify file to specify your Mapbox token,
+* Set an environment variable (MapboxAccessToken) - through the use of a
+  webpack loader or browserify transform, see the hello-world examples
+  for details.
+* Provide a token in the URL. See documentation of react-map-gl.
diff --git a/docs/whats-new.md b/docs/whats-new.md
@@ -1,16 +1,17 @@
 # deck.gl v4.0
 
-Release date: Target: March 24, 2017
+Release date: March 31, 2017
 
 ## Highlights
 
 - **New Geospatial Layers** GeoJsonLayer, PathLayer, PolygonLayer, IconLayer,
-  GridLayer, HexagonLayer, PointCloudLayer.
-- **New Aggregating Layers** PointDensityGridLayer and PointDensityHexagonLayer
-  automatically "bin" your point data into grid cells or hexagons.
+  GridCellLayer, HexagonCellLayer, PointCloudLayer.
+- **New Aggregating Layers** GridLayer and HexagonLayer now join the ScreenGridLayer
+  in a growing family of layers that automatically "bin" your point data, in this
+  case into grid cells or hexagons.
 - **New Examples** deck.gl now provides multiple stand-alone examples, with minimal
   configuration files (`package.json`, `webpack.config.js` etc) intended to make it
-  easy to just copy an example folder and get things working.
+  easy to just copy an example folder and get an app up and running in minutes.
 - **Unified 64-bit Layers** - 64-bit Layers are now unified with 32-bit layers, use `fp64` prop.
 - **Library Size Reduction** - A number of npm package dependencies have been
   trimmed from deck.gl, and the distribution has initial support for "tree-shaking"
@@ -20,16 +21,19 @@ Release date: Target: March 24, 2017
 - **Model Matrix Support** - Model matrix support for the `METER_OFFSET` projection mode
   enables arbitrary coordinate transforms (translations, rotations, scaling etc)
   to be applied on individual layer enabling scene graph like layer composition and animation.
-- **Documentation** Improved and reorganized in response to user feedbacks.
+- **Documentation** Improved and reorganized in response to user feedback.
 - **Experimental Features** Experimental support for non-Mercator projections and
   rendering effects (e.g. Reflections)
 
 ## New Layers
 
-* GeoJsonLayer
+### GeoJsonLayer
 
-A composite layer that parses geojson and renders it as a `PathLayer`
-and a `PolygonLayer`.
+A layer that parses and renders GeoJson. Supports all GeoJson primitives
+(polygons, lines and points).
+The GeoJsonLayer is an example of a composite layer that instantiates other layers
+(in this case `PathLayer`, `PolygonLayer` and `ScatterplotLayer`) to do the actual
+rendering. This layer replaces the now deprecated family of `ChoroplethLayer`s.
 
 ### PathLayer
 
@@ -65,9 +69,6 @@ Draws a LiDAR point cloud. Supports point position/normal/color.
 
 ## Improvements to all Layers
 
-### TBD - support immutable data/ES6 containers?
-
-
 ### Support for Per-Layer Model Matrix
 
 Each layer now supports a `modelMatrix` property that can be used to
@@ -81,8 +82,6 @@ specify a local coordinate system for the data in that layer:
   possibilities as individual layers can be scaled, rotated, translated etc
   with very low computational cost (i.e. without modifying the data).
 
-TBD - `layerMatrix` vs. `modelMatrix`
-
 
 ### UpdateTriggers now accept Accessor Names
 
@@ -95,14 +94,13 @@ to supply names of `accessors`.
 
 ### More intuitive mouse events
 
-`onHover` is now only fired on entering/exiting an object instead of on mouse move.
-
-`onClick` is now only fired on the picked layer instead of all pickable layers.
+* `onHover` is now only fired on entering/exiting an object instead of on mouse move.
+* `onClick` is now only fired on the picked layer instead of all pickable layers.
 
 
 ## New Features for Layer Subclassing
 
-### **Overridable shaders
+### Overridable Shaders
 
 All layers now have a `getShaders` method that can
 be overriden by subclasses, enables reuse of all layer code while just
@@ -152,7 +150,7 @@ over logging of attribute updates.
 
 ## Library Improvements
 
-JavaScript build tooling continues to evolve rapidly and efforts have
+JavaScript build tooling continues to evolve and efforts have
 been made to ensure deck.gl supports several popular new tooling setups:
 
 * **Dependency Reduction** The number of npm dependencies (both in `deck.gl`,