diff options
author | Minh Nguyễn <mxn@1ec5.org> | 2015-12-06 15:24:58 -0800 |
---|---|---|
committer | Minh Nguyễn <mxn@1ec5.org> | 2016-01-05 12:41:54 -0800 |
commit | 1420a49689c3b48dd429fb5a3640596a9e7c9623 (patch) | |
tree | 4acf7523051ede1230439d6fbb099dadf411f334 /platform | |
parent | e26b218883c3357f38dd8ff5490b453dabffc590 (diff) | |
download | qtlocation-mapboxgl-1420a49689c3b48dd429fb5a3640596a9e7c9623.tar.gz |
[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.
Diffstat (limited to 'platform')
-rw-r--r-- | platform/ios/INSTALL.md | 7 | ||||
-rw-r--r-- | platform/ios/bitrise.yml | 3 | ||||
-rwxr-xr-x | platform/ios/scripts/install.sh | 7 | ||||
-rwxr-xr-x | platform/ios/scripts/package.sh | 49 |
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/' {} \; |