[ios] Adds guides to documentation sidebar (#7488)

Initial set of guides focused on runtime styling

20 files changed, 250 insertions, 9 deletions

diff --git a/platform/ios/README.md b/platform/ios/README.md
index 2350d1e527..3d4cc3ff2b 100644
--- a/platform/ios/README.md
+++ b/platform/ios/README.md
@@ -9,4 +9,4 @@ This repository is for day-to-day development of the SDK. Building the SDK yours
 * [Integrating the Mapbox iOS SDK into your application](INSTALL.md)
 * [Contributing to the Mapbox iOS SDK](DEVELOPING.md)
 
-![](screenshot.png)
+![](docs/img/screenshot.png)
diff --git a/platform/ios/docs/doc-README.md b/platform/ios/docs/doc-README.md
index 22493b1502..e91bc0b1cc 100644
--- a/platform/ios/docs/doc-README.md
+++ b/platform/ios/docs/doc-README.md
@@ -2,7 +2,7 @@
 
 The Mapbox iOS SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/), applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://www.mapbox.com/developers/vector-tiles/), and renders them using OpenGL.
 
-![Mapbox iOS SDK screenshots](screenshot.png)
+![Mapbox iOS SDK screenshots](img/screenshot.png)
 
 For setup information, check out the [Mapbox iOS SDK homepage](https://www.mapbox.com/ios-sdk/). For detailed usage instructions, read “[First steps with the Mapbox iOS SDK](https://www.mapbox.com/help/first-steps-ios-sdk/)” and consult the [online examples](https://www.mapbox.com/ios-sdk/examples/). A [full changelog](https://github.com/mapbox/mapbox-gl-native/blob/master/platform/ios/CHANGELOG.md) is also available.
 
diff --git a/platform/ios/docs/guides/Adding Points to a Map.md b/platform/ios/docs/guides/Adding Points to a Map.md
new file mode 100644
index 0000000000..5f89f4d6a8
--- /dev/null
+++ b/platform/ios/docs/guides/Adding Points to a Map.md
@@ -0,0 +1,84 @@
+# Adding Points to a Map
+
+Mapbox offers a few different ways to add points to a map, each with different tradeoffs.
+
+## MGLPointAnnotation
+
+It's straightforward to add an annotation to a map. You can use `MGLPointAnnotation` as is, or you can subclass it to add annotations with richer data.
+
+```swift
+let annotation = MGLPointAnnotation()
+annotation.coordinate = CLLocationCoordinate2D(latitude: 45.5076, longitude: -122.6736)
+annotation.title = "Bobby's Coffee"
+annotation.subtitle = "Coffeeshop"
+mapView.addAnnotation(annotation)
+```
+
+See the `MGLMapViewDelegate` method `-mapView:annotationCanShowCallout:` and similar methods for allowing interaction with a callout.
+
+## Displaying annotations
+
+There are two basic ways to display the annotations you've added to a map, each with their own tradeoffs.
+
+### Annotation Images (`MGLAnnotationImage`)
+
+Annotation images are the quickest and most performant ways to display annotations, and you can provide your own custom annotation images ([example](https://www.mapbox.com/ios-sdk/examples/marker-image/)).
+
+By default, annotations added to the map are displayed with a red pin. If you'd like to customize this annotation, you can implement `MGLMapViewDelegate` `-mapView:imageForAnnotation:`.
+
+**Pros**
+
+* The easiest way to display a marker on a map
+* Easily customizable with any `UIImage`
+* High performance as the images are rendered directly in OpenGL
+
+**Cons**
+
+* Annotation images are purely static
+* No control over z-ordering
+* Limits to the size and number of images you can add
+
+### Annotation Views (`MGLAnnotationView`)
+
+If you're looking to add custom UIViews or have annotations that are dynamic or animatable, consider an `MGLAnnotationView` instead of an `MGLAnnotationImage` ([example](https://www.mapbox.com/ios-sdk/examples/annotation-views/)).
+
+Annotation views are a big advantage over annotation images when you need every annotation to be unique. For example, annotation views are ideal if as an example you want to show user locations on a map using their profile pictures.
+
+To use annotation views, you'll need to implement `MGLMapViewDelegate` `-mapView:viewForAnnotation` and provide a custom `MGLAnnotationView` (`UIView`) subclass.
+
+**Pros**
+
+* Custom, native UIViews
+* No limit on style or image size
+* Full support for animations
+* Familiar API to MapKit
+* Relative control over z-ordering using the `zPosition` property on `CALayer`
+
+**Cons**
+
+* Performance implications:
+    * UIViews are inherently slow to render compared to OpenGL, more apparent if you're adding many views or moving the map rapidly
+    * In some cases, you might consider runtime styling
+
+## Advanced: Runtime Styling
+
+If you're looking for absolute full control of how points are displayed on a map, consider [runtime styling](runtime-styling.html).
+
+You can use `MGLPointFeature` or any of the other [style feature subclasses](Style%20Features.html) to add points and shapes to an `MGLShapeSource`.
+
+From there, you can create one or many `MGLSymbolStyleLayer` or `MGLCircleStyleLayer` layers to filter and style points for display on the map ([example](https://www.mapbox.com/ios-sdk/examples/runtime-multiple-annotations)).
+
+**Pros**
+
+* Most powerful option
+* Highest performance (rendered in GL directly)
+* SDK-level support for labels rendered together with icons
+* Finer control of z-ordering
+    * Rendering respects ordering within the data source
+    * Otherwise layers are lightweight so you can create a new layer for each level you need
+
+**Cons**
+
+* Currently you must implement your own tap gesture recognizer together with `MGLMapView.visibleFeaturesAtPoint` to recognize taps and manually show callouts ([example](https://www.mapbox.com/ios-sdk/examples/select-feature)).
+* Currently no SDK support for animations. If you need animations, consider using an NSTimer and updating the layer properties accordingly.
+
diff --git a/platform/ios/docs/Info.plist Keys.md b/platform/ios/docs/guides/Info.plist Keys.md
index 34d3da9e29..c5c7cf1d85 100644
--- a/platform/ios/docs/Info.plist Keys.md
+++ b/platform/ios/docs/guides/Info.plist Keys.md
@@ -1,6 +1,6 @@
 # Info.plist Keys
 
-The Mapbox iOS SDK supports custom `Info.plist` keys in your application in order to configure various settings. 
+The Mapbox iOS SDK supports custom `Info.plist` keys in your application in order to configure various settings.
 
 ## MGLMapboxAccessToken
 
@@ -8,13 +8,13 @@ Set the [Mapbox access token](https://www.mapbox.com/help/define-access-token/)
 
 Mapbox-hosted vector tiles and styles require an API access token, which you can obtain from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/). Access tokens associate requests to Mapbox’s vector tile and style APIs with your Mapbox account. They also deter other developers from using your styles without your permission.
 
-As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. 
+As an alternative, you can use `+[MGLAccountManager setAccessToken:]` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private.
 
 ## MGLMapboxAPIBaseURL
 
-Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. 
+Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used.
 
-The default value is `https://api.mapbox.com`. 
+The default value is `https://api.mapbox.com`.
 
 ## MGLMapboxMetricsEnabledSettingShownInApp
 
diff --git a/platform/ios/docs/guides/Runtime Styling.md b/platform/ios/docs/guides/Runtime Styling.md
new file mode 100644
index 0000000000..afc2ccae87
--- /dev/null
+++ b/platform/ios/docs/guides/Runtime Styling.md
@@ -0,0 +1,57 @@
+# Runtime Styling
+
+Mapbox's runtime styling features allow you direct control over every layer in your maps with code. It's now possible create dynamic maps and visualizations that aren't possible with other mobile maps SDKs.
+
+Runtime styling expands upon the design power of [Mapbox Studio](https://www.mapbox.com/mapbox-studio/) and exposes all of the same properties and attributes directly to mobile developers in our SDK.
+
+Beyond the custom styled maps that you can create with Mapbox Studio, you can now change the look and feel of your map on the fly having maps in your app visually respond to user interaction or or context. Or leverage the power of OpenGL for highly performant and complex data visualizations. Now it's possible to mix in your own data and bring your map to life.
+
+## Example use cases
+
+As an example of what's possible with runtime styling, consider some of the following use cases:
+
+### Styling maps on the fly
+
+At runtime, you can tailor the map specifically to your user interface. Tweak colors, text, and icons to match the style to your brand.
+
+![dynamic styles](img/runtime-styling/DynamicStyles.gif "an example showing dynamic styles")
+
+For maps that aren't going to change in response to custom data or user interaction, consider creating a custom map style with [Mapbox Studio](https://www.mapbox.com/mapbox-studio/).
+
+### Map interactivity
+
+You can customize the map to the point of having it respond dynamically based on the actions your users are taking. Increase the text size of streets while a user is driving, emphasize points of interest tailored to a user's preferences, or change your UI if users are at parks, trails, landmarks, or rivers.
+
+![emojis](img/runtime-styling/Emoji.gif "an example showing emoji interaction")
+
+### Powerful data visualization
+
+Mapbox maps are built on top of OpenGL and can support rendering data without the traditional overhead of `UIView`-based map annotations.
+
+Mapbox can support data visualizations that were slow or impossible with traditional map SDKs. Render heatmaps, visualize population density, or even go so far as updating the snow levels in the mountains to match recent snowfall.
+
+![hex bins](img/runtime-styling/HexBins.gif "an example using hex bins")
+![population](img/runtime-styling/Population.gif "an example showing population density")
+![snow levels](img/runtime-styling/SnowLevels.gif "an example visualizing snow levels in the mountains")
+
+### Powerful annotations
+
+The Mapbox SDK gives you access to all of the same tools we use to render our default map styles. Instead of using generic pin markers, enrich your place data or custom polygons with icons and labels that make your maps stand out.
+
+![custom annotations](img/runtime-styling/CustomAnnotations.gif "an example showing custom annotations")
+
+### Custom shapes
+
+Draw custom shapes on the map the same way you would a custom `UIView` or `CALayer`. These shapes keep their geographic scale and are perfect for visualizing everything from indoor floor plans to metro systems to hurricane tracks.
+
+<!-- TODO: custom storm tracks -->
+<!-- TODO: metro system -->
+<!-- TODO: indoor maps -->
+
+## Resources
+
+* [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/)
+* [Mapbox Studio](https://www.mapbox.com/mapbox-studio/)
+* [iOS code examples](https://www.mapbox.com/ios-sdk/examples/)
+
+Contact support@mapbox.com with futher questions about how to leverage runtime styling.
diff --git a/platform/ios/docs/guides/Working with Mapbox Studio.md b/platform/ios/docs/guides/Working with Mapbox Studio.md
new file mode 100644
index 0000000000..97aa614c41
--- /dev/null
+++ b/platform/ios/docs/guides/Working with Mapbox Studio.md
@@ -0,0 +1,97 @@
+# Working with Mapbox Studio
+
+[Mapbox Studio](http://mapbox.com/studio) is Mapbox's tool for creating custom map styles. It also serves as an excellent tool for rapidly prototyping dynamic maps and runtime styling interactions for iOS.
+
+## Creating a base style
+
+Start by heading to [mapbox.com/studio](http://mapbox.com/studio) and creating a new style. Any style that's close to what you'll be using in your app is ideal.
+
+## Prototyping with data
+
+The goal in using Mapbox Studio for prototyping runtime styling implementations is to test data presentation assumptions as quickly as possible. With the Mapbox Studio tools, you can import a small subset of your own real data, fake data as a placeholder, or prototype with existing Mapbox data.
+
+### Prototyping with Mapbox data
+The default [Mapbox Streets tileset](https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v7/) might offer data similar to your own that you can use to style before you swap in your own data at runtime.
+
+For example, if you're looking to prototype points of interest, consider the `poi_label` layer; if you want to style GPS traces, the `roads` layer might be a good proxy. Take a look at what's available in [Mapbox Streets](https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v7/): there's probably a layer that closely matches your data.
+
+### Importing real data
+If you can't find a good approximation for your data in Mapbox Streets, consider uploading a small subset of your data into Mapbox Studio as a custom tileset.
+
+From the [Mapbox Studio Dashboard](https://www.mapbox.com/studio/), click `Tilesets` in the sidebar, then click `New Tileset` to get started with most common geo file formats including KML, GPX, GeoJSON, Shapefiles, and CSV.
+
+### Faking placeholder data
+If you don't have any custom data on hand in a format that works easily with the Tileset importer, you can fake placeholder data with the Dataset Editor.
+
+From the [Mapbox Studio Dashboard](https://www.mapbox.com/studio/), click `Datasets` in the sidebar, then click on `New Dataset` to get started.
+
+Zoom into your desired location and use the draw tools on the left to start creating a set of sample data.
+
+![create shapes](img/studio-workflow/create-polygons.gif)
+
+Next, add data properties you'd like to use to drive your style. Consider categorical properties or numeric properties that you'd use to filter and group your data. Text properties can be used to display icons or labels.
+
+![add properties](img/studio-workflow/add-properties.gif)
+
+**General Guidelines:**
+
+* Text along a line: add line with a text property
+* Text at specific points on a line or polygon: in addition to the line, create points at the specific points you'd like with text properties
+* If you want circles where scale doesn't matter relative to the geography (e.g. always 20 pixels), you can add as a point and style with a circle layer or a symbol
+* If you want circles or arcs where the scale matters (e.g. 10 mile radius), you'll need to approximately freehand a polygon, and you can create more precisely later in code.
+
+When you're done, save your dataset and export as a tileset. When that's complete, add your tileset to your style.
+
+### Import into your style
+
+1. Click `New Layer`
+2. Select your tileset
+3. Select your shape type:
+    * `Symbol`: best for text and icons
+    * `Line`: best for lines or adding strokes to polygons
+    * `Fill`: best for filling polygons
+    * `Circle`: for styling points or nodes along a line or polygon as circles. If you need circles of a fixed radius (e.g. 1 mile radius), you should model your data as a polygon.
+4. Add filters if necessary
+    * You can selectively filter your data by their properties to group and style separately
+5. Click on `Create Layer`
+
+## Styling with Mapbox Studio
+
+Mapbox Studio shines for styling your data and the process is much faster than attempting to style natively.
+
+There are some nuances to understand between the different layer types and how they work together. Don't be afraid to use the layers sidebar to peek into the techniques used to style the stock Mapbox maps. You can duplicate these layers, re-point the source to your own data, and tweak as needed.
+
+**Best Practices:**
+
+* Layers are cheap, so duplicate and update filters liberally.
+* If you'd like to stroke polygons you'll need to use two layers: one a fill and one a stroked line.
+* If you want to stroke a line, create two layers, one for the default stroke and one with a wider width for its casing
+* If you intend to animate properties or transition between values, consider creating separate layers for each state and toggling visibility to visualize the difference.
+
+## Implement on iOS with runtime styling
+
+Once you're happy with the styles you've created, it's time to [get setup with Mapbox in your app](https://www.mapbox.com/ios-sdk/).
+
+To implement your prototypes with runtime styling:
+
+1. Implement `MGLMapViewDelegate` `-mapView:didFinishLoadingStyle:`
+2. Add your real data as a source
+    * This can be done using vector data from tileset editor ([example](https://www.mapbox.com/ios-sdk/examples/runtime-circle-styles)), custom vector tiles, added as GeoJSON ([example](https://www.mapbox.com/ios-sdk/examples/runtime-add-line), or added manually through the app via `MGLShapeSource` ([example](https://www.mapbox.com/ios-sdk/examples/runtime-multiple-annotations))
+3. For each layer you've prototyped in studio, add it's corresponding `MGLStyleLayer` subclass: `MGLSymbolStyleLayer`, `MGLLineStyleLayer`, `MGLFillStyleLayer`, or `MGLCircleStyleLayer`.
+
+**Translating style attributes from Studio**
+For each property you've edited in Studio, you can hover over the property name to find it's corresponding property in the iOS SDK. They're generally the camelCased version of the Property ID.
+
+![property values](img/studio-workflow/property-values.png)
+
+**Translating stop functions**
+It's possible to use stop functions in Mapbox Studio to transition the style of a layer by it's zoom level (e.g. a line that gets wider as you zoom in). These can be translated in the mobile SDKs using `+[MGLSyleValue valueWithInterpolationBase:stops:]`. The rate of change between stops in studio is represented by `interpolationBase`.
+
+![Stop functions](img/studio-workflow/stop-functions.png)
+
+## Resources
+
+* [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/)
+* [Mapbox Studio](https://www.mapbox.com/mapbox-studio/)
+* [iOS code examples](https://www.mapbox.com/ios-sdk/examples/)
+
diff --git a/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif b/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif
new file mode 100644
index 0000000000..dee99d01fd
--- /dev/null
+++ b/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif
diff --git a/platform/ios/docs/img/runtime-styling/DynamicStyles.gif b/platform/ios/docs/img/runtime-styling/DynamicStyles.gif
new file mode 100644
index 0000000000..b42d30c602
--- /dev/null
+++ b/platform/ios/docs/img/runtime-styling/DynamicStyles.gif
diff --git a/platform/ios/docs/img/runtime-styling/Emoji.gif b/platform/ios/docs/img/runtime-styling/Emoji.gif
new file mode 100644
index 0000000000..fc50b28972
--- /dev/null
+++ b/platform/ios/docs/img/runtime-styling/Emoji.gif
diff --git a/platform/ios/docs/img/runtime-styling/HexBins.gif b/platform/ios/docs/img/runtime-styling/HexBins.gif
new file mode 100644
index 0000000000..c810085f22
--- /dev/null
+++ b/platform/ios/docs/img/runtime-styling/HexBins.gif
diff --git a/platform/ios/docs/img/runtime-styling/Population.gif b/platform/ios/docs/img/runtime-styling/Population.gif
new file mode 100644
index 0000000000..81b6c6310f
--- /dev/null
+++ b/platform/ios/docs/img/runtime-styling/Population.gif
diff --git a/platform/ios/docs/img/runtime-styling/SnowLevels.gif b/platform/ios/docs/img/runtime-styling/SnowLevels.gif
new file mode 100644
index 0000000000..8ee2f9fddd
--- /dev/null
+++ b/platform/ios/docs/img/runtime-styling/SnowLevels.gif
diff --git a/platform/ios/screenshot.png b/platform/ios/docs/img/screenshot.png
index 62c04746d4..62c04746d4 100644
--- a/platform/ios/screenshot.png
+++ b/platform/ios/docs/img/screenshot.png
diff --git a/platform/ios/docs/img/studio-workflow/add-properties.gif b/platform/ios/docs/img/studio-workflow/add-properties.gif
new file mode 100644
index 0000000000..740fae655b
--- /dev/null
+++ b/platform/ios/docs/img/studio-workflow/add-properties.gif
diff --git a/platform/ios/docs/img/studio-workflow/create-polygons.gif b/platform/ios/docs/img/studio-workflow/create-polygons.gif
new file mode 100644
index 0000000000..6eb2c0afb8
--- /dev/null
+++ b/platform/ios/docs/img/studio-workflow/create-polygons.gif
diff --git a/platform/ios/docs/img/studio-workflow/property-values.png b/platform/ios/docs/img/studio-workflow/property-values.png
new file mode 100644
index 0000000000..95704241f9
--- /dev/null
+++ b/platform/ios/docs/img/studio-workflow/property-values.png
diff --git a/platform/ios/docs/img/studio-workflow/stop-functions.png b/platform/ios/docs/img/studio-workflow/stop-functions.png
new file mode 100644
index 0000000000..4affecf005
--- /dev/null
+++ b/platform/ios/docs/img/studio-workflow/stop-functions.png
diff --git a/platform/ios/docs/pod-README.md b/platform/ios/docs/pod-README.md
index 78647b2603..b1a763bcf1 100644
--- a/platform/ios/docs/pod-README.md
+++ b/platform/ios/docs/pod-README.md
@@ -4,7 +4,7 @@ The Mapbox iOS SDK is an open-source framework for embedding interactive map vie
 
 For more information, check out the [Mapbox iOS SDK homepage](https://www.mapbox.com/ios-sdk/) and the [full changelog](https://github.com/mapbox/mapbox-gl-native/blob/master/platform/ios/CHANGELOG.md) online.
 
-[![](https://raw.githubusercontent.com/mapbox/mapbox-gl-native/master/platform/ios/screenshot.png)]()
+[![](https://raw.githubusercontent.com/mapbox/mapbox-gl-native/master/platform/ios/docs/img/screenshot.png)]()
 
 ## Installation
 
diff --git a/platform/ios/jazzy.yml b/platform/ios/jazzy.yml
index 7d8d82988d..1f1e48fce5 100644
--- a/platform/ios/jazzy.yml
+++ b/platform/ios/jazzy.yml
@@ -15,6 +15,9 @@ hide_documentation_coverage: Yes
 custom_categories:
   - name: Guides
     children:
+      - Adding Points to a Map
+      - Runtime Styling
+      - Working with Mapbox Studio
       - Info.plist Keys
   - name: Maps
     children:
diff --git a/platform/ios/scripts/document.sh b/platform/ios/scripts/document.sh
index 78eb5121eb..634f4de5dc 100755
--- a/platform/ios/scripts/document.sh
+++ b/platform/ios/scripts/document.sh
@@ -30,7 +30,7 @@ sed -n -e '/^## /{' -e ':a' -e 'n' -e '/^## /q' -e 'p' -e 'ba' -e '}' platform/i
 rm -rf ${OUTPUT}
 mkdir -p ${OUTPUT}
 
-cp platform/ios/screenshot.png "${OUTPUT}"
+cp -r platform/ios/docs/img "${OUTPUT}/img"
 
 DEFAULT_THEME="platform/darwin/docs/theme"
 THEME=${JAZZY_THEME:-$DEFAULT_THEME}
@@ -46,7 +46,7 @@ jazzy \
     --framework-root ${FRAMEWORK_PATH} \
     --umbrella-header "${FRAMEWORK_PATH}/Headers/Mapbox.h" \
     --readme ${README} \
-    --documentation="platform/ios/docs/Info.plist Keys.md" \
+    --documentation="platform/ios/docs/guides/*.md" \
     --root-url https://www.mapbox.com/ios-sdk/api/${RELEASE_VERSION}/ \
     --theme ${THEME} \
     --output ${OUTPUT}