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, 160 insertions, 0 deletions

diff --git a/platform/ios/DEVELOPING.md b/platform/ios/DEVELOPING.md
new file mode 100644
index 0000000000..c8445aade3
--- /dev/null
+++ b/platform/ios/DEVELOPING.md
@@ -0,0 +1,47 @@
+# Contributing to the Mapbox iOS SDK
+
+This document explains how to build the Mapbox iOS SDK and the osxapp demo application for the purpose of developing the SDK itself.
+
+### 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
+
+[Install core dependencies](../../INSTALL.md), then run
+
+    make iproj
+
+Which will create and open an Xcode project that can build the entire library from source, as well as an Objective-C test app.
+
+If you don't have an Apple Developer account, change the destination from "My Mac" to a simulator such as "iPhone 6" before you run and build the app.
+
+### 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/)._
+
+Set up the access token by editing the scheme for the application target, then adding an environment variable with the name `MAPBOX_ACCESS_TOKEN`.
+
+![edit scheme](https://cloud.githubusercontent.com/assets/98601/5460702/c4610262-8519-11e4-873a-8597821da468.png)
+
+![setting access token in Xcode scheme](https://cloud.githubusercontent.com/assets/162976/5349358/0a086f00-7f8c-11e4-8433-bdbaccda2b58.png)
+
+### Test
+
+Run
+
+    make itest
+
+To run the included integration tests on the command line.
+
+If you want to run the tests in Xcode instead, first `make ipackage` to create a local static library version, then open `test/ios/ios-tests.xcodeproj`, and lastly `Command + U` on the `Mapbox GL Tests` application target.
+
+### Usage
+
+- Pan to move
+- Pinch to zoom
+- Use two fingers to rotate
+- Double-tap to zoom in one level
+- Two-finger single-tap to zoom out one level
+- Double-tap, long-pressing the second, then pan up and down to "quick zoom" (iPhone only, meant for one-handed use)
+- Use the debug menu to add test annotations, reset position, and cycle through the debug options.
diff --git a/platform/ios/INSTALL.md b/platform/ios/INSTALL.md
new file mode 100644
index 0000000000..f3afaea822
--- /dev/null
+++ b/platform/ios/INSTALL.md
@@ -0,0 +1,101 @@
+# Integrating the Mapbox iOS SDK into your application
+
+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.
+
+   ```
+   curl -L -o appledoc.zip https://github.com/tomaz/appledoc/releases/download/v2.2-963/appledoc.zip
+   unzip appledoc.zip
+   cp appledoc /usr/local/bin
+   cp -Rf Templates/ ~/.appledoc
+   ```
+
+1. Run `make ipackage`. The packaging script will produce the statically-linked `libMapbox.a`, `Mapbox.bundle` for resources, a `Headers` folder, and a `Docs` folder with HTML API documentation.
+
+### 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/)._
+
+Set up the access token by editing the scheme for the application target, then adding an environment variable with the name `MAPBOX_ACCESS_TOKEN`.
+
+![edit scheme](https://cloud.githubusercontent.com/assets/98601/5460702/c4610262-8519-11e4-873a-8597821da468.png)
+
+![setting access token in Xcode scheme](https://cloud.githubusercontent.com/assets/162976/5349358/0a086f00-7f8c-11e4-8433-bdbaccda2b58.png)
+
+### Test
+
+In the context of your own app, you can now either:
+
+#### CocoaPods
+
+Currently, until [#1437](https://github.com/mapbox/mapbox-gl-native/issues/1437) is completed, to install a _development version_ of Mapbox GL using CocoaPods you will need to build it from source manually per above.
+
+1. Zip up the build product.
+
+    ```
+    cd build/ios/pkg/static
+    ZIP=mapbox-ios-sdk.zip
+    rm -f ../${ZIP}
+    zip -r ../${ZIP} *
+    ```
+
+1. Modify a custom `Mapbox-iOS-SDK.podspec` to download this zip file.
+
+    ```rb
+    {...}
+
+    m.source = {
+        :http => "http://{...}/mapbox-ios-sdk.zip",
+        :flatten => true
+    }
+
+    {...}
+    ```
+
+1. Update your app's `Podfile` to point to the `Mapbox-iOS-SDK.podspec`.
+
+    ```rb
+    pod 'Mapbox-iOS-SDK', :podspec => 'http://{...}/Mapbox-iOS-SDK.podspec'
+    ```
+
+1. Run `pod update` to grab the newly-built library.
+
+#### Binary
+
+1. Built from source manually per above.
+
+1. Copy the contents of `build/ios/pkg/static` into your project. It should happen automatically, but ensure that:
+
+   - `Headers` is in your *Header Search Paths* (`HEADER_SEARCH_PATHS`) build setting.
+   - `Mapbox.bundle` is in your target's *Copy Bundle Resources* build phase.
+   - `libMapbox.a` is in your target's *Link Binary With Libraries* build phase.
+
+1. Add the following Cocoa framework dependencies to your target's *Link Binary With Libraries* build phase:
+
+   - `GLKit.framework`
+   - `ImageIO.framework`
+   - `MobileCoreServices.framework`
+   - `QuartzCore.framework`
+   - `SystemConfiguration.framework`
+   - `libc++.dylib`
+   - `libsqlite3.dylib`
+   - `libz.dylib`
+
+1. Add `-ObjC` to your target's "Other Linker Flags" build setting (`OTHER_LDFLAGS`).
+
+## Troubleshooting
+
+On OS X, you can also try clearing the Xcode cache with `make clear_xcode_cache`.
diff --git a/platform/ios/README.md b/platform/ios/README.md
new file mode 100644
index 0000000000..a6752c61e6
--- /dev/null
+++ 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)