From b4d55ecc8ae94e75b710ec2080d78b2193b621b2 Mon Sep 17 00:00:00 2001 From: Bart Louwers Date: Mon, 12 Feb 2024 17:18:14 +0100 Subject: [PATCH] Build DocC documentation for iOS (#2104) --- .github/workflows/ios-ci.yml | 13 ++++ platform/ios/.gitignore | 1 + platform/ios/MapLibre.docc/MapLibre.md | 83 ++++++++++++++++++++++++++ platform/ios/scripts/docc.sh | 59 ++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 platform/ios/MapLibre.docc/MapLibre.md create mode 100755 platform/ios/scripts/docc.sh diff --git a/.github/workflows/ios-ci.yml b/.github/workflows/ios-ci.yml index f0591df1b..b0c008c22 100644 --- a/.github/workflows/ios-ci.yml +++ b/.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' diff --git a/platform/ios/.gitignore b/platform/ios/.gitignore index b2d1f64c9..14aef746c 100644 --- a/platform/ios/.gitignore +++ b/platform/ios/.gitignore @@ -38,6 +38,7 @@ test/fixtures/storage/assets.zip buck-out .buckd MapLibre.xcodeproj +.docc-build # Visual Studio Code .vscode diff --git a/platform/ios/MapLibre.docc/MapLibre.md b/platform/ios/MapLibre.docc/MapLibre.md new file mode 100644 index 000000000..fee157ba3 --- /dev/null +++ b/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`` diff --git a/platform/ios/scripts/docc.sh b/platform/ios/scripts/docc.sh new file mode 100755 index 000000000..9a1da58cc --- /dev/null +++ b/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 \ No newline at end of file