Build DocC documentation for iOS (#2104)

.github/workflows/ios-ci.yml

@@ -183,6 +183,19 @@ jobs:
       - if: github.event_name == 'pull_request'
         uses: ./.github/actions/save-pr-number
 
+      - name: Build DocC documentation main branch
+        if: github.ref == 'refs/heads/main'
+        run: |
+          scripts/docc.sh
+
+      - name: Deploy DocC documentation (main) 🚀
+        if: github.ref == 'refs/heads/main'
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
+        with:
+          branch: gh-pages
+          folder: platform/ios/build/docs
+          target-folder: ios/latest/
+
       # Make Metal XCFramework release
       - name: Should make release?
         if: github.event.inputs.release == 'full' || github.event.inputs.release == 'pre'

platform/ios/.gitignore

@@ -38,6 +38,7 @@ test/fixtures/storage/assets.zip
 buck-out
 .buckd
 MapLibre.xcodeproj
+.docc-build
 
 # Visual Studio Code
 .vscode

platform/ios/MapLibre.docc/MapLibre.md

@@ -0,0 +1,83 @@
+# ``MapLibre``
+
+@Metadata {
+    @Available(iOS, introduced: "12.0")
+}
+
+Powerful, free and open-source mapping toolkit with full control over data sources and styling.
+
+## Overview
+
+[MapLibre Native](https://github.com/maplibre/maplibre-native) is a map rendering toolkit with support for iOS. It can be used as an alternative to MapKit. You have full control over the data sources used for rendering the map, as well as the styling. You can even participate in the development as MapLibre Native is free and open-source project.
+> Note: For information on creating and modifying map styles, see the [MapLibre Style Spec documentation](https://maplibre.org/maplibre-style-spec/).
+
+## Topics
+
+### Map
+
+- ``MLNMapView``
+
+### Style Layers
+
+- ``MLNBackgroundStyleLayer``
+- ``MLNCircleStyleLayer``
+- ``MLNFillExtrusionStyleLayer``
+- ``MLNFillStyleLayer``
+- ``MLNForegroundStyleLayer``
+- ``MLNHeatmapStyleLayer``
+- ``MLNHillshadeStyleLayer``
+- ``MLNLineStyleLayer``
+- ``MLNRasterStyleLayer``
+- ``MLNStyleLayer``
+- ``MLNSymbolStyleLayer``
+- ``MLNVectorStyleLayer``
+
+### Sources
+
+- ``MLNComputedShapeSource``
+- ``MLNImageSource``
+- ``MLNRasterDEMSource``
+- ``MLNRasterTileSource``
+- ``MLNShapeSource``
+- ``MLNSource``
+- ``MLNTileSource``
+
+### Shapes
+
+- ``MLNEmptyFeature``
+- ``MLNMultiPoint``
+- ``MLNMultiPolygon``
+- ``MLNMultiPolygonFeature``
+- ``MLNMultiPolyline``
+- ``MLNMultiPolylineFeature``
+- ``MLNMultiPolylineFeature``
+- ``MLNPointAnnotation``
+- ``MLNPointCollection``
+- ``MLNPointCollectionFeature``
+- ``MLNPolygon``
+- ``MLNPolyline``
+- ``MLNPolylineFeature``
+- ``MLNShape``
+- ``MLNShapeCollection``
+- ``MLNShapeCollectionFeature``
+
+### Snapshotter
+
+- ``MLNMapSnapshot``
+- ``MLNMapSnapshotOptions``
+- ``MLNMapSnapshotter``
+
+### Offline support
+
+- ``MLNOfflinePack``
+- ``MLNOfflineRegion``
+- ``MLNOfflineStorage``
+- ``MLNShapeOfflineRegion``
+- ``MLNTilePyramidOfflineRegion``
+
+### Annotations
+
+- ``MLNAnnotationImage``
+- ``MLNAnnotationView``
+- ``MLNPointFeature``
+- ``MLNPointFeatureCluster``

platform/ios/scripts/docc.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# This script is a bit of a hack to generate DocC documentation until Bazel has support for it.
+# https://github.com/bazelbuild/rules_apple/issues/2241
+# To use this script, make sure the XCFramework is built with Bazel (see ios-ci.yml).
+# Then to start a local preview, run:
+# $ scripts/docc.sh bazel
+# You can also build the documentation locally
+# $ scripts/docc.sh
+# Then go to build/ios and run
+# $ python3 -m http.server
+# Go to http://localhost:8000/documentation/maplibre/
+
+cmd="convert"
+if [[ "$1" == "preview" ]]; then
+  cmd="preview"
+fi
+
+SDK_PATH=$(xcrun -sdk iphoneos --show-sdk-path)
+
+build_dir=build
+
+rm -rf "$build_dir"/symbol-graphs
+rm -rf "$build_dir"/headers/MapLibre
+rm -rf "$build_dir"/MapLibre.xcframework
+
+mkdir "$build_dir"/symbol-graphs
+mkdir -p "$build_dir"/headers/MapLibre
+
+# unzip built XCFramework in build dir
+unzip ../../bazel-bin/platform/ios/MapLibre.dynamic.xcframework.zip -d "$build_dir"
+
+# copy all public headers from XCFramework
+cp "$build_dir"/MapLibre.xcframework/ios-arm64/MapLibre.framework/Headers/*.h "$build_dir"/headers/MapLibre
+
+xcrun --toolchain swift clang \
+     -extract-api \
+     --product-name=MapLibre \
+     -isysroot $SDK_PATH \
+     -F "$SDK_PATH"/System/Library/Frameworks \
+     -I "$PWD" \
+     -I "$(realpath ../darwin/src)" \
+     -I "$build_dir"/headers \
+     -x objective-c-header  \
+     -o "$build_dir"/symbol-graphs/MapLibre.symbols.json  \
+     "$build_dir"/headers/MapLibre/*.h
+
+export DOCC_HTML_DIR=$(dirname $(xcrun --toolchain swift --find docc))/../share/docc/render
+$(xcrun --find docc) "$cmd" MapLibre.docc \
+    --fallback-display-name "MapLibre Native for iOS" \
+    --fallback-bundle-identifier org.swift.MyProject \
+    --fallback-bundle-version 0.0.1  \
+    --additional-symbol-graph-dir "$build_dir"/symbol-graphs \
+    --output-path "$build_dir"/MapLibre.doccarchive
+
+if [[ "$cmd" == "convert" ]]; then
+  rm -rf build/docs
+  $(xcrun --find docc) process-archive transform-for-static-hosting "$build_dir"/MapLibre.doccarchive --output-path build/docs
+fi