Rewrote documentation

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/.

3 files changed, 63 insertions, 0 deletions

diff --git a/platform/osx/DEVELOPING.md b/platform/osx/DEVELOPING.md
new file mode 100644
index 0000000000..3233b6302c
--- /dev/null
+++ 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
new file mode 100644
index 0000000000..4016c360c6
--- /dev/null
+++ b/platform/osx/INSTALL.md
@@ -0,0 +1,30 @@
+# Integrating the Mapbox OS X SDK into your 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
+
+1. Copy `gyp/build/Release/Mapbox.framework` into your project.
+
+1. In the project editor, select your application target, go to the General tab, and add `Mapbox.framework` to the *Embedded Binaries* section.
+
+1. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target. In the Info tab, set `MGLMapboxAccessToken` to your access token. You can obtain one from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/).
+
+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
new file mode 100644
index 0000000000..d96ae4947f
--- /dev/null
+++ 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)