[ios] Generate API documentation using jazzy

Replaced appledoc usage with jazzy, which understands modern Objective-C syntax by virtue of using Clang ASTs. Nevertheless, we have to make lots of changes to our documentation syntax, which was tailored to appledocs quirks. The new syntax jives much better with what Xcode expects in terms of auto-indentation and Quick Help.

Fixes #1420.

4 files changed, 29 insertions, 37 deletions

diff --git a/platform/ios/INSTALL.md b/platform/ios/INSTALL.md
index f3afaea822..2c36b5953c 100644
--- a/platform/ios/INSTALL.md
+++ b/platform/ios/INSTALL.md
@@ -14,13 +14,10 @@ The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK. Th
 
 1. [Install core dependencies](../../INSTALL.md).
 
-1. Install [appledoc](http://appledoc.gentlebytes.com/appledoc/) for API docs generation.
+1. Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
 
    ```
-   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
+   [sudo] gem install jazzy
    ```
 
 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.
diff --git a/platform/ios/bitrise.yml b/platform/ios/bitrise.yml
index e725efb201..25860485a4 100644
--- a/platform/ios/bitrise.yml
+++ b/platform/ios/bitrise.yml
@@ -34,8 +34,7 @@ workflows:
 
             brew install pkgconfig
             brew install automake
-            brew install homebrew/versions/appledoc22
-            brew link --force appledoc22
+            gem install jazzy
     - script:
         title: Run make ipackage-sim
         run_if: '{{enveq "SKIPCI" "false"}}'
diff --git a/platform/ios/scripts/install.sh b/platform/ios/scripts/install.sh
index 23000e160b..437193b1f2 100755
--- a/platform/ios/scripts/install.sh
+++ b/platform/ios/scripts/install.sh
@@ -14,10 +14,7 @@ brew install git
 mapbox_time "install_awscli" \
 brew install awscli
 
-mapbox_time "install_appledoc" \
-wget https://github.com/tomaz/appledoc/releases/download/v2.2-963/appledoc.zip && \
-tar xvzf appledoc.zip && \
-cp appledoc /usr/local/bin && \
-cp -Rf Templates/ ~/.appledoc
+mapbox_time "install_jazzy" \
+gem install jazzy
 
 mkdir -p ${KIF_SCREENSHOTS}
diff --git a/platform/ios/scripts/package.sh b/platform/ios/scripts/package.sh
index f1a67bb8f2..b7de1830a5 100755
--- a/platform/ios/scripts/package.sh
+++ b/platform/ios/scripts/package.sh
@@ -6,7 +6,6 @@ set -u
 
 NAME=Mapbox
 OUTPUT=build/ios/pkg
-IOS_SDK_VERSION=`xcrun --sdk iphoneos --show-sdk-version`
 LIBUV_VERSION=1.7.5
 ENABLE_BITCODE=YES
 
@@ -29,6 +28,12 @@ else # e.g. "make ipackage-strip"
     GCC_GENERATE_DEBUGGING_SYMBOLS="NO"
 fi
 
+SDK=iphonesimulator
+if [[ ${BUILD_FOR_DEVICE} == true ]]; then
+    SDK=iphoneos
+fi
+IOS_SDK_VERSION=`xcrun --sdk ${SDK} --show-sdk-version`
+
 function step { >&2 echo -e "\033[1m\033[36m* $@\033[0m"; }
 function finish { >&2 echo -en "\033[0m"; }
 trap finish EXIT
@@ -116,9 +121,13 @@ mkdir -p "${OUTPUT}/static/${NAME}.bundle"
 cp -pv platform/ios/resources/* "${OUTPUT}/static/${NAME}.bundle"
 
 step "Creating API Docs..."
-if [ -z `which appledoc` ]; then
-    echo "Unable to find appledoc. See https://github.com/mapbox/mapbox-gl-native/blob/master/docs/BUILD_IOS_OSX.md"
-    exit 1
+if [ -z `which jazzy` ]; then
+    step "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/docs/BUILD_IOS_OSX.md"
+        exit 1
+    fi
 fi
 DOCS_OUTPUT="${OUTPUT}/static/Docs"
 DOCS_VERSION=$( git tag | grep ^ios | sed 's/^ios-//' | sort -r | grep -v '\-rc.' | grep -v '\-pre.' | sed -n '1p' | sed 's/^v//' )
@@ -129,24 +138,14 @@ cat ios/docs/pod-README.md > ${README}
 echo >> ${README}
 echo -n "#" >> ${README}
 cat CHANGELOG.md | sed -n "/^## iOS ${DOCS_VERSION}/,/^##/p" | sed '$d' >> ${README}
-# Copy headers to a temporary location where we can substitute macros that appledoc doesn't understand.
-cp -r "${OUTPUT}/static/Headers" /tmp/mbgl
-perl \
-    -pi \
-    -e 's/NS_(?:(MUTABLE)_)?(ARRAY|SET|DICTIONARY)_OF\(\s*(.+?)\s*\)/NS\L\u$1\u$2\E <$3>/g' \
-    /tmp/mbgl/Headers/*.h
-perl \
-    -i -p0 \
-    -e 's/^#if\s+!\s*TARGET_OS_IPHONE\s*(?:&&[^\n]+)?\n.+?\n#endif//gms' \
-    /tmp/mbgl/Headers/*.h
-appledoc \
-    --output ${DOCS_OUTPUT} \
-    --project-name "Mapbox iOS SDK ${DOCS_VERSION}" \
-    --project-company Mapbox \
-    --create-html \
-    --no-create-docset \
-    --no-install-docset \
-    --company-id com.mapbox \
-    --index-desc ${README} \
-    /tmp/mbgl/Headers
-cp ${README} "${OUTPUT}/static"
+
+jazzy \
+    --sdk ${SDK} \
+    --github-file-prefix https://github.com/mapbox/mapbox-gl-native/tree/${HASH} \
+    --module-version ${DOCS_VERSION} \
+    --readme ${README} \
+    --root-url https://www.mapbox.com/ios-sdk/api/${DOCS_VERSION}/ \
+    --output ${DOCS_OUTPUT}
+# https://github.com/realm/jazzy/issues/411
+find ${DOCS_OUTPUT} -name *.html -exec \
+    perl -pi -e 's/Mapbox\s+(Docs|Reference)/Mapbox iOS SDK $1/' {} \;