[osx] Added OS X SDK documentation target

Added a target, script, and make rule for generating OS X SDK documentation with jazzy, along with a docset cover page. Switched the umbrella header from framework header syntax to user header syntax so SourceKit can find all the headers. Fixes #4871.
2016-05-09 16:03:16 -07:00
parent 7332ae0073
commit 5616cd2bb1
6 changed files with 225 additions and 0 deletions
--- a/3
+++ b/3
@@ -66,6 +66,9 @@ test-osx: osx node_modules/express
 	  -configuration $(BUILDTYPE) \
 	  -workspace $(OSX_WORK_PATH) -scheme CI test $(XCPRETTY)

+xdocument:
+	OUTPUT=$(OUTPUT) ./platform/osx/scripts/document.sh
+
 genstrings:
 	genstrings -u -o platform/osx/sdk/Base.lproj platform/darwin/src/*.{m,mm}
 	genstrings -u -o platform/osx/sdk/Base.lproj platform/osx/src/*.{m,mm}
--- a/platform/osx/docs/doc-README.md
+++ b/platform/osx/docs/doc-README.md
@@ -0,0 +1,9 @@
+# [Mapbox OS X SDK](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/osx/)
+
+The Mapbox OS X SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa applications on OS X 10.10.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the [Mapbox GL 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.
+
+<img alt="" src="https://raw.githubusercontent.com/mapbox/mapbox-gl-native/master/platform/osx/screenshot.png" width="645">
+
+For setup information, consult the README.md that comes with this documentation. The [Mapbox iOS SDK](https://www.mapbox.com/ios-sdk/)’s [API documentation](https://www.mapbox.com/ios-sdk/api/) and [online examples](https://www.mapbox.com/ios-sdk/examples/) apply to the Mapbox OS X SDK with few differences, mostly around unimplemented features like user location tracking. A [full changelog](https://github.com/mapbox/mapbox-gl-native/blob/master/platform/osx/CHANGELOG.md) is also available.
+
+Mapbox does not officially support the OS X SDK to the same extent as the iOS SDK; however, [bug reports and pull requests](https://github.com/mapbox/mapbox-gl-native/issues/) are certainly welcome.
--- a/platform/osx/docs/pod-README.md
+++ b/platform/osx/docs/pod-README.md
@@ -0,0 +1,43 @@
+# [Mapbox OS X SDK](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/osx/)
+
+The Mapbox OS X SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa applications on OS X 10.10.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the [Mapbox GL 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.
+
+<img alt="" src="https://raw.githubusercontent.com/mapbox/mapbox-gl-native/master/platform/osx/screenshot.png" width="645">
+
+## Installation
+
+1. Open the project editor, select your application target, then go to the General tab. Drag Mapbox.framework from the `dynamic` folder into the “Embedded Binaries” section. (Don’t drag it into the “Linked Frameworks and Libraries” section; Xcode will add it there automatically.) In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.
+
+1. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target, then go to the Info tab. Under the “Custom iOS Target Properties” section, set `MGLMapboxAccessToken` to your access token. You can obtain an access token from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/).
+
+## Usage
+
+In a storyboard or XIB, add a view to your view controller. (Drag Custom View from the Object library to the View Controller scene on the Interface Builder canvas.) In the Identity inspector, set the view’s custom class to `MGLMapView`. If you need to manipulate the map view programmatically:
+
+1. Switch to the Assistant Editor.
+1. Import the `Mapbox` module.
+1. Connect the map view to a new outlet in your view controller class. (Control-drag from the map view in Interface Builder to a valid location in your view controller implementation.) The resulting outlet declaration should look something like this:
+
+```objc
+// ViewController.m
+@import Mapbox;
+
+@interface ViewController : NSViewController
+
+@property (strong) IBOutlet MGLMapView *mapView;
+
+@end
+```
+
+```swift
+// ViewController.swift
+import Mapbox
+
+class ViewController: NSViewController {
+    @IBOutlet var mapView: MGLMapView!
+}
+```
+
+Full API documentation is included in this package, within the `documentation` folder. The [Mapbox iOS SDK](https://www.mapbox.com/ios-sdk/)’s [API documentation](https://www.mapbox.com/ios-sdk/api/) and [online examples](https://www.mapbox.com/ios-sdk/examples/) apply to the Mapbox OS X SDK with few differences, mostly around unimplemented features like user location tracking.
+
+Mapbox does not officially support the OS X SDK to the same extent as the iOS SDK; however, [bug reports and pull requests](https://github.com/mapbox/mapbox-gl-native/issues/) are certainly welcome.
--- a/platform/osx/jazzy.yml
+++ b/platform/osx/jazzy.yml
@@ -0,0 +1,71 @@
+module: Mapbox
+author: Mapbox
+author_url: https://www.mapbox.com/
+github_url: https://github.com/mapbox/mapbox-gl-native
+copyright: '© 2014–2016 [Mapbox](https://www.mapbox.com/). See [license](https://github.com/mapbox/mapbox-gl-native/blob/master/LICENSE.md) for more details.'
+
+head: |
+  <link rel='shortcut icon' href='https://www.mapbox.com/img/favicon.ico' type='image/x-icon' />
+
+objc: Yes
+skip_undocumented: Yes
+hide_documentation_coverage: Yes
+umbrella_header: src/Mapbox.h
+framework_root: ../darwin/src
+
+custom_categories:
+  - name: Maps
+    children:
+      - MGLAccountManager
+      - MGLMapCamera
+      - MGLMapDebugMaskOptions
+      - MGLMapView
+      - MGLMapViewDelegate
+      - MGLStyle
+      - MGLStyleDefaultVersion
+      - MGLUserTrackingMode
+  - name: Annotations
+    children:
+      - MGLAnnotation
+      - MGLAnnotationImage
+      - MGLMultiPoint
+      - MGLPointAnnotation
+      - MGLPolygon
+      - MGLPolyline
+      - MGLOverlay
+      - MGLShape
+  - name: Offline Maps
+    children:
+      - MGLOfflineRegion
+      - MGLOfflineStorage
+      - MGLOfflinePack
+      - MGLOfflinePackAdditionCompletionHandler
+      - MGLOfflinePackErrorNotification
+      - MGLOfflinePackErrorUserInfoKey
+      - MGLOfflinePackMaximumCountUserInfoKey
+      - MGLOfflinePackMaximumMapboxTilesReachedNotification
+      - MGLOfflinePackProgress
+      - MGLOfflinePackProgressChangedNotification
+      - MGLOfflinePackProgressUserInfoKey
+      - MGLOfflinePackRemovalCompletionHandler
+      - MGLOfflinePackState
+      - MGLOfflinePackStateUserInfoKey
+      - MGLTilePyramidOfflineRegion
+  - name: Geometry
+    children:
+      - MGLClockDirectionFormatter
+      - MGLCompassDirectionFormatter
+      - MGLCoordinateBounds
+      - MGLCoordinateBoundsEqualToCoordinateBounds
+      - MGLCoordinateBoundsGetCoordinateSpan
+      - MGLCoordinateBoundsIsEmpty
+      - MGLCoordinateBoundsMake
+      - MGLCoordinateBoundsOffset
+      - MGLCoordinateFormatter
+      - MGLCoordinateSpan
+      - MGLCoordinateSpanEqualToCoordinateSpan
+      - MGLCoordinateSpanMake
+      - MGLCoordinateSpanZero
+      - MGLDegreesFromRadians
+      - MGLRadiansFromDegrees
+      - MGLStringFromCoordinateBounds
--- a/platform/osx/osx.xcodeproj/project.pbxproj
+++ b/platform/osx/osx.xcodeproj/project.pbxproj
@@ -542,6 +542,23 @@
 		};
 /* End PBXHeadersBuildPhase section */

+/* Begin PBXLegacyTarget section */
+		DAAA17961CE13BAE00731EFE /* docs */ = {
+			isa = PBXLegacyTarget;
+			buildArgumentsString = "xdocument OUTPUT=build/osx/pkg/documentation";
+			buildConfigurationList = DAAA17991CE13BAE00731EFE /* Build configuration list for PBXLegacyTarget "docs" */;
+			buildPhases = (
+			);
+			buildToolPath = /usr/bin/make;
+			buildWorkingDirectory = ../../;
+			dependencies = (
+			);
+			name = docs;
+			passBuildSettingsInEnvironment = 1;
+			productName = docs;
+		};
+/* End PBXLegacyTarget section */
+
 /* Begin PBXNativeTarget section */
 		DA839E911CC2E3400062CAFB /* osxapp */ = {
 			isa = PBXNativeTarget;
@@ -611,6 +628,9 @@
 					DA839E911CC2E3400062CAFB = {
 						CreatedOnToolsVersion = 7.3;
 					};
+					DAAA17961CE13BAE00731EFE = {
+						CreatedOnToolsVersion = 7.3.1;
+					};
 					DAE6C3271CC30DB200DB3429 = {
 						CreatedOnToolsVersion = 7.3;
 					};
@@ -635,6 +655,7 @@
 				DA839E911CC2E3400062CAFB /* osxapp */,
 				DAE6C3271CC30DB200DB3429 /* dynamic */,
 				DAE6C3301CC30DB200DB3429 /* test */,
+				DAAA17961CE13BAE00731EFE /* docs */,
 			);
 		};
 /* End PBXProject section */
@@ -908,6 +929,31 @@
 			};
 			name = Release;
 		};
+		DAAA17971CE13BAE00731EFE /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
+				DEBUGGING_SYMBOLS = YES;
+				DEBUG_INFORMATION_FORMAT = dwarf;
+				GCC_GENERATE_DEBUGGING_SYMBOLS = YES;
+				GCC_OPTIMIZATION_LEVEL = 0;
+				OTHER_CFLAGS = "";
+				OTHER_LDFLAGS = "";
+				PRODUCT_NAME = "$(TARGET_NAME)";
+			};
+			name = Debug;
+		};
+		DAAA17981CE13BAE00731EFE /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
+				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+				OTHER_CFLAGS = "";
+				OTHER_LDFLAGS = "";
+				PRODUCT_NAME = "$(TARGET_NAME)";
+			};
+			name = Release;
+		};
 		DAE6C33F1CC30DB200DB3429 /* Debug */ = {
 			isa = XCBuildConfiguration;
 			baseConfigurationReference = DAE6C3C51CC31F9100DB3429 /* mbgl.xcconfig */;
@@ -1041,6 +1087,14 @@
 			defaultConfigurationIsVisible = 0;
 			defaultConfigurationName = Release;
 		};
+		DAAA17991CE13BAE00731EFE /* Build configuration list for PBXLegacyTarget "docs" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				DAAA17971CE13BAE00731EFE /* Debug */,
+				DAAA17981CE13BAE00731EFE /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+		};
 		DAE6C3431CC30DB200DB3429 /* Build configuration list for PBXNativeTarget "dynamic" */ = {
 			isa = XCConfigurationList;
 			buildConfigurations = (
--- a/platform/osx/scripts/document.sh
+++ b/platform/osx/scripts/document.sh
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -e
+set -o pipefail
+set -u
+
+if [ -z `which jazzy` ]; then
+    echo "Installing jazzy…"
+    gem install jazzy
+    if [ -z `which jazzy` ]; then
+        echo "Unable to install jazzy. See https://github.com/mapbox/mapbox-gl-native/blob/master/platform/osx/INSTALL.md"
+        exit 1
+    fi
+fi
+
+OUTPUT=${OUTPUT:-documentation}
+
+BRANCH=$( git describe --tags --match=osx-v*.*.* --abbrev=0 )
+SHORT_VERSION=$( echo ${BRANCH} | sed 's/^osx-v//' )
+RELEASE_VERSION=$( echo ${SHORT_VERSION} | sed -e 's/^osx-v//' -e 's/-.*//' )
+
+SWIFT_VERSION=$(xcrun swift -version | head -n 1 | sed -e 's/^Apple Swift version //' -e 's/ .*$//')
+
+rm -rf /tmp/mbgl
+mkdir -p /tmp/mbgl/
+README=/tmp/mbgl/README.md
+cp platform/osx/docs/doc-README.md "${README}"
+# http://stackoverflow.com/a/4858011/4585461
+echo "## Changes in version ${RELEASE_VERSION}" >> "${README}"
+sed -n -e '/^## /{' -e ':a' -e 'n' -e '/^##/q' -e 'p' -e 'ba' -e '}' platform/osx/CHANGELOG.md >> "${README}"
+
+rm -rf ${OUTPUT}
+mkdir -p ${OUTPUT}
+
+jazzy \
+    --config platform/osx/jazzy.yml \
+    --sdk macosx \
+    --swift-version $SWIFT_VERSION \
+    --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${BRANCH} \
+    --module-version ${SHORT_VERSION} \
+    --readme ${README} \
+    --output ${OUTPUT}
+# https://github.com/realm/jazzy/issues/411
+find ${OUTPUT} -name *.html -exec \
+    perl -pi -e 's/Mapbox\s+(Docs|Reference)/Mapbox OS X SDK $1/' {} \;