Rewrote documentation

1ec5 · 1ec5 · commit f8f735b57450 · 2016-01-05T08:04:16.000-08:00
Rewrote some copy to provide more context and link to more GL-related repos, including GL JS. Put the various SDKs in a table so we can show the various CI bot status images.

Integrated target list into the relevant documents. Rewrote large portions of iOS and OS X setup documentation to guide normal developers to more friendly places. Combined some Android documentation.

Moved SDK-specific documentation into platform/. Added a temporary readme in ios/ that points to the one in platform/ios/.
diff --git a/INSTALL.md b/INSTALL.md
@@ -51,20 +51,10 @@ dependencies:
 
 ## 3: Setting up a development environment & building
 
-This depends on what operating systems you're using, and what platforms you're
-developing for:
+See the relevant SDK documentation for next steps:
 
-**on OS X**
-
-* [For OS X on OS X](docs/DEVELOP_OSX.md)
-* [For iOS on OS X](docs/DEVELOP_IOS_OSX.md)
-* [For Android on OS X](docs/DEVELOP_ANDROID_OSX.md)
-
-**on Linux**
-
-* [For Linux on Linux](docs/DEVELOP_LINUX.md)
-* [For Android on Linux](docs/DEVELOP_ANDROID_LINUX.md)
-
-**Node.js bindings**
-
-* [Developing Node.js bindings](docs/DEVELOP_NODE.md)
+* [Mapbox Android SDK](platform/android/)
+* [Mapbox iOS SDK](platform/ios/)
+* [Mapbox OS X SDK](platform/osx/)
+* [Mapbox GL Native on Linux](platform/linux/)
+* [node-mapbox-gl-native](platform/node/)
diff --git a/README.md b/README.md
@@ -1,29 +1,23 @@
 # Mapbox GL Native
 
-[![Travis](https://api.travis-ci.org/mapbox/mapbox-gl-native.svg?branch=master)](https://travis-ci.org/mapbox/mapbox-gl-native/builds) [![Bitrise](https://www.bitrise.io/app/7514e4cf3da2cc57.svg?token=OwqZE5rSBR9MVWNr_lf4sA&branch=master)](https://www.bitrise.io/app/7514e4cf3da2cc57)
+A library for embedding interactive vector maps into native applications on multiple platforms. It takes stylesheets that conform to the [Mapbox GL Style Specification](https://github.com/mapbox/mapbox-gl-style-spec/), applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec), and renders them using OpenGL. [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is the WebGL-based counterpart, designed for use on the Web.
 
-An OpenGL-based renderer for [Mapbox Vector Tiles](https://www.mapbox.com/blog/vector-tiles), consisting of a C++ library for Linux and SDK bindings for iOS, Android, Node.js, and OS X.
+## The Mapbox GL ecosystem
 
-**This repository is for development on Mapbox GL Native itself.**
+This repository hosts the cross-platform Mapbox GL Native library, plus convenient SDKs for several platforms. The cross-platform library comes with a [GLFW](https://github.com/glfw/glfw)-based demo application for Ubuntu Linux and OS X. The SDKs target the usual languages on their respective platforms:
 
-If you want to use products _based on_ Mapbox GL, check out:
+SDK | Languages | Build status
+----|-----------|-------------
+[Mapbox GL Native](INSTALL.md) | C++14 | [![Travis](https://travis-ci.org/mapbox/mapbox-gl-native.svg?branch=master)](https://travis-ci.org/mapbox/mapbox-gl-native/builds)
+[Mapbox Android SDK](platform/android/) | Java | [![Bitrise](https://www.bitrise.io/app/79cdcbdc42de4303.svg?token=_InPF8bII6W7J6kFr-L8QQ&branch=master)](https://www.bitrise.io/app/79cdcbdc42de4303)
+[Mapbox iOS SDK](platform/ios/) | Objective-C or Swift | [![Bitrise](https://www.bitrise.io/app/7514e4cf3da2cc57.svg?token=OwqZE5rSBR9MVWNr_lf4sA&branch=master)](https://www.bitrise.io/app/7514e4cf3da2cc57)
+[Mapbox OS X SDK](platform/osx/) | Objective-C or Swift | [![Bitrise](https://www.bitrise.io/app/155ef7da24b38dcd.svg?token=4KSOw_gd6WxTnvGE2rMttg&branch=master)](https://www.bitrise.io/app/155ef7da24b38dcd)
+[node-mapbox-gl-native](platform/node/) | Node.js | [![Travis](https://travis-ci.org/mapbox/mapbox-gl-native.svg?branch=master)](https://travis-ci.org/mapbox/mapbox-gl-native/builds)
 
-- [Mapbox Mobile](http://mapbox.com/mobile) — iOS and Android native development libraries
-- [`mapbox-gl-native`](https://www.npmjs.com/package/mapbox-gl-native) - Node.js native module
-- [`react-native-mapbox-gl`](https://github.com/mapbox/react-native-mapbox-gl) — React Native library
-- [`qmapboxgl`](https://github.com/tmpsantos/qmapboxgl) — Qt library
-- [`Mapbox Cordova Plugin`](http://plugins.telerik.com/cordova/plugin/mapbox) - Telerik's Apache Cordova plugin
+Additional Mapbox GL Native–based libraries are developed outside of this repository:
 
---
+* [React Native Mapbox GL](https://github.com/mapbox/react-native-mapbox-gl) for React Native applications on iOS and Android
+* [QMapboxGL](https://github.com/tmpsantos/qmapboxgl) for Qt-based applications
+* Telerik’s [Mapbox plugin](http://plugins.telerik.com/cordova/plugin/mapbox) for Apache Cordova applications
 
-## Targets
-
-* Ubuntu Linux
-* OS X 10.10+
-* iOS 7.0+
-  * iPhone 4S and above (5, 5c, 5s, 6, 6 Plus)
-  * iPad 2 and above (3, 4, Mini, Air, Mini 2, Air 2)
-  * iPod touch 5th gen and above
-* Android 4.0.3+ (API level 15+)
-
-See [`INSTALL.md`](./INSTALL.md) for development setup and install instructions, including dependencies.
+If your platform or hybrid application framework isn’t listed here, consider embedding [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) using the standard Web capabilities on your platform.
diff --git a/docs/ANDROID_DEVICE.md b/docs/ANDROID_DEVICE.md
diff --git a/docs/ANDROID_SIMULATOR.md b/docs/ANDROID_SIMULATOR.md
diff --git a/docs/DEVELOP_NODE.md b/docs/DEVELOP_NODE.md
diff --git a/docs/DEVELOP_OSX.md b/docs/DEVELOP_OSX.md
diff --git a/ios/README.md b/ios/README.md
@@ -0,0 +1 @@
+The Mapbox iOS SDK is [located here](../platform/ios/).
diff --git a/platform/android/DISTRIBUTE.md b/platform/android/DISTRIBUTE.md
diff --git a/platform/android/INSTALL_LINUX.md b/platform/android/INSTALL_LINUX.md
diff --git a/platform/android/INSTALL_OSX.md b/platform/android/INSTALL_OSX.md
@@ -1,4 +1,4 @@
-# Developing for Android on OS X
+# Installing the Mapbox Android SDK on OS X
 
 Install Oracle JDK 7+ and Android Studio:
 
diff --git a/platform/android/README.md b/platform/android/README.md
@@ -0,0 +1,46 @@
+# [Mapbox Android SDK](https://www.mapbox.com/android-sdk/)
+
+[![Bitrise](https://www.bitrise.io/app/79cdcbdc42de4303.svg?token=_InPF8bII6W7J6kFr-L8QQ&branch=master)](https://www.bitrise.io/app/79cdcbdc42de4303)
+
+A library based on [Mapbox GL Native](../../README.md) for embedding interactive vector maps into Java applications on Android devices.
+
+This repository is for day-to-day development of the SDK. Building the SDK yourself requires [a number of dependencies and steps](../../INSTALL.md) that are unnecessary for developing production applications. For production applications, please consider installing an official, prebuilt release instead; see the [Mapbox Android SDK website](https://www.mapbox.com/android-sdk/) for installation instructions.
+
+## Installing the SDK
+
+* [Installing the Mapbox Android SDK on Linux](INSTALL_LINUX.md)
+* [Installing the Mapbox Android SDK on OS X](INSTALL_OSX.md)
+
+## Setting up the Android emulator
+
+The Mapbox Android SDK requires Android 4.0.3+ (API level 15+).
+
+If you want to run the test app in the emulator, we recommend the x86 build because it will run a lot faster.
+
+First ensure you have an `MAPBOX_ACCESS_TOKEN` environment variable set, as described below. Then, create an x86 build:
+
+    make android-lib-x86
+
+In Android Studio, create an x86 AVD (Android Virtual Device):
+
+- Open AVD Manager via the Tools menu -> Android -> AVD Manager
+- Click "Create Virtual Device" at the bottom on AVD Manager window
+- Select one of the device profiles, for example the Nexus 4
+- Click "Next"
+- Select a Lollipop or Kitkat release with ABI of x86. If the line is greyed out click Download to download the OS files.
+- Click "Next"
+- Under "Emulated Performance" check "Host GPU" and uncheck "Store a snapshot for faster startup"
+- Click "Finish"
+- Close the AVD Manager
+
+Now when you run or debug the Android project you will see a window "Choose Device". Select your new AVD from drop down under "Launch emulator". If you select "Use same device for future launches" Android Studio will remember the selection and not ask again.
+
+## Running Mapbox GL Native on a hardware Android device
+
+The Mapbox Android SDK requires Android 4.0.3+ (API level 15+).
+
+First read the [Google documentation](http://developer.android.com/tools/device.html) to set up your device and your OS to connect to the device.
+
+When you plug your device in and then run or debug the Android project you will see a window "Choose Device". Choose your device from the "Choose a running device" list.
+
+If your device does not show up, double check the [Google documentation](http://developer.android.com/tools/device.html).
diff --git a/platform/ios/DEVELOPING.md b/platform/ios/DEVELOPING.md
@@ -1,16 +1,14 @@
-# Developing for iOS on OS X
+# Contributing to the Mapbox iOS SDK
 
-This process gives you a native iOS app for testing changes to mapbox-gl-native
-on a simulator or device. Normally production use of the library is via a
-precompiled binary linked into the app target: this process instead compiles
-Mapbox GL Native from source along with your application, so it can include
-latest development and your own modifications.
+This document explains how to build the Mapbox iOS SDK and the osxapp demo application for the purpose of developing the SDK itself.
 
-Developing for iOS implies an OS X host system.
+### Requirements
+
+The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK and require Xcode on a computer running OS X.
 
 ### Build
 
-Run
+[Install core dependencies](../../INSTALL.md), then run
 
     make iproj
 
diff --git a/platform/ios/INSTALL.md b/platform/ios/INSTALL.md
@@ -1,9 +1,19 @@
-# Building Mapbox GL Native for iOS
+# Integrating the Mapbox iOS SDK into your application
 
-This section is for people contributing to Mapbox GL directly in the context of their own app.
+This document explains how to build a development version of Mapbox iOS SDK for the purpose of incorporating it into your own Cocoa Touch application.
+
+### Requirements
+
+The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK. They are intended to run on iOS 7.0 and above on the following devices and their simulators:
+
+* iPhone 4S and above (5, 5c, 5s, 6, 6 Plus)
+* iPad 2 and above (3, 4, Mini, Air, Mini 2, Air 2)
+* iPod touch 5th generation and above
 
 ### Build
 
+1. [Install core dependencies](../../INSTALL.md).
+
 1. Install [appledoc](http://appledoc.gentlebytes.com/appledoc/) for API docs generation.
 
    ```
diff --git a/platform/ios/README.md b/platform/ios/README.md
@@ -0,0 +1,12 @@
+# [Mapbox iOS SDK](https://www.mapbox.com/ios-sdk/)
+
+[![Bitrise](https://www.bitrise.io/app/7514e4cf3da2cc57.svg?token=OwqZE5rSBR9MVWNr_lf4sA&branch=master)](https://www.bitrise.io/app/7514e4cf3da2cc57)
+
+A library based on [Mapbox GL Native](../../README.md) for embedding interactive vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder.
+
+This repository is for day-to-day development of the SDK. Building the SDK yourself requires [a number of dependencies and steps](../../INSTALL.md) that are unnecessary for developing production applications. For production applications, please consider installing an official, prebuilt release instead; see the [Mapbox iOS SDK website](https://www.mapbox.com/ios-sdk/) for installation instructions.
+
+* [Integrating the Mapbox iOS SDK into your application](INSTALL.md)
+* [Contributing to the Mapbox iOS SDK](DEVELOPING.md)
+
+![](../../ios/screenshot.png)
diff --git a/platform/linux/README.md b/platform/linux/README.md
@@ -1,5 +1,7 @@
 # Linux
 
+A simple map application and test suite for Linux based on [Mapbox GL Native](../../README.md) and [GLFW](https://github.com/glfw/glfw).
+
 We are using Ubuntu for development. While the software should work on other distributions as well, we are not providing explicit build instructions here.
 
 This process gives you a Linux desktop app built on a Linux host system.
diff --git a/platform/node/DEVELOPING.md b/platform/node/DEVELOPING.md
@@ -0,0 +1,29 @@
+# Developing the Mapbox GL Native Node.js module
+
+This document explains how to build the [Node.js](https://nodejs.org/) bindings for [../../README.md](Mapbox GL Native) for contributing to the development of the bindings themselves. If you just want to use the module, you can simply install it via `npm`; see [README.md](README.md) for installation and usage instructions.
+
+## Building
+
+To develop these bindings, you’ll need to build them from source. Building requires [installing all of the basic dependencies needed for Mapbox GL Native](../../INSTALL.md), then running:
+
+    npm install --build-from-source
+
+From the root directory. This will compile the Node.js bindings and install module dependencies.
+
+To recompile just the C++ code while developing, run `make node`.
+
+To create an Xcode project and use a GUI debugger in the case of a crash, run `make xnode`.
+
+## Testing
+
+To test the Node.js bindings:
+
+```
+npm test
+```
+
+To run the visual render test suite:
+
+```
+npm run test-suite
+```
diff --git a/platform/node/README.md b/platform/node/README.md
@@ -1,6 +1,7 @@
 # node-mapbox-gl-native
 
-[![NPM](https://nodei.co/npm/mapbox-gl-native.png)](https://npmjs.org/package/mapbox-gl-native)
+[![NPM](https://nodei.co/npm/mapbox-gl-native.png)](https://npmjs.org/package/mapbox-gl-native)  
+[![Travis](https://travis-ci.org/mapbox/mapbox-gl-native.svg?branch=master)](https://travis-ci.org/mapbox/mapbox-gl-native/builds)
 
 ## Installing
 
@@ -245,3 +246,7 @@ map.render({}, function(err, image) {
 });
 
 ```
+
+## Contributing
+
+See [DEVELOPING.md](DEVELOPING.md) for instructions on building this module for development.
diff --git a/platform/osx/DEVELOPING.md b/platform/osx/DEVELOPING.md
@@ -0,0 +1,23 @@
+# Contributing to the Mapbox OS X SDK
+
+This document explains how to build the Mapbox OS X SDK for contributing to the development of the SDK itself.
+
+### Requirements
+
+The Mapbox OS X SDK and the osxapp demo application run on OS X 10.10.0 and above.
+
+### Build
+
+1. [Install core dependencies](../../INSTALL.md).
+1. Run `make xproj`.
+1. Switch to the osxsdk or osxapp scheme. The former builds just the Cocoa framework, while the latter also builds a Cocoa demo application based on it.
+
+### Access tokens
+
+The demo applications use Mapbox vector tiles, which require a Mapbox account and API access token. Obtain an access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). You will be prompted for this access token the first time you launch the demo application.
+
+### Usage
+
+Through the OS X SDK, the demo application supports a variety of standard gestures and keyboard shortcuts. For more details, open Mapbox GL Help from the Help menu.
+
+You can also [integrate the Mapbox OS X SDK into your own Cocoa application](INSTALL.md).
diff --git a/platform/osx/INSTALL.md b/platform/osx/INSTALL.md
@@ -1,9 +1,14 @@
-# Building Mapbox GL Native for OS X
+# Integrating the Mapbox OS X SDK into your application
 
-This project provides an OS X SDK analogous to the Mapbox iOS SDK. Mapbox does not officially support it to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome. This document explains how to build the OS X SDK and integrate it into your own Cocoa application.
+This document explains how to build the Mapbox OS X SDK and integrate it into your own Cocoa application.
+
+### Requirements
+
+The Mapbox OS X SDK requires the OS X 10.10.0 SDK or above.
 
 ### Build
 
+1. [Install core dependencies](../../INSTALL.md).
 1. Run `make xpackage`, which produces a `Mapbox.framework` in the `gyp/build/Release/` folder.
 
 ### Install
@@ -16,6 +21,10 @@ This project provides an OS X SDK analogous to the Mapbox iOS SDK. Mapbox does n
 
 1. In a XIB or storyboard, add a Custom View and set its custom class to `MGLMapView`. If you need to manipulate the map view programmatically, import the `Mapbox` module (Swift) or `Mapbox.h` umbrella header (Objective-C).
 
+## Use
+
+The [Mapbox iOS SDK’s API documentation](https://www.mapbox.com/ios-sdk/api/3.0.1/) applies to the Mapbox OS X SDK with few differences, mostly around unimplemented features like user location tracking.
+
 ## Troubleshooting
 
 You can also try clearing the Xcode cache with `make clear_xcode_cache`.
diff --git a/platform/osx/README.md b/platform/osx/README.md
@@ -0,0 +1,10 @@
+# Mapbox OS X SDK
+
+[![Bitrise](https://www.bitrise.io/app/155ef7da24b38dcd.svg?token=4KSOw_gd6WxTnvGE2rMttg&branch=master)](https://www.bitrise.io/app/155ef7da24b38dcd)
+
+A library based on [Mapbox GL Native](../../README.md) for embedding interactive vector maps into Cocoa applications on OS X 10.10.0 and above using Objective-C, Swift, or Interface Builder.
+
+This SDK is analogous to the Mapbox iOS SDK, and much of the iOS SDK documentation applies here. Mapbox does not officially support the OS X to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome.
+
+* [Integrating the Mapbox OS X SDK into your application](INSTALL.md)
+* [Contributing to the Mapbox OS X SDK](DEVELOPING.md)

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+The Mapbox iOS SDK is [located here](../platform/ios/).`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Developing for Android on OS X`
	`1`	`+# Installing the Mapbox Android SDK on OS X`
`2`	`2`
`3`	`3`	`Install Oracle JDK 7+ and Android Studio:`
`4`	`4`