From 17e6e7cdcb47c5f384aa181d79481f9084cab879 Mon Sep 17 00:00:00 2001 From: Bart Louwers Date: Wed, 14 Feb 2024 11:09:22 +0100 Subject: [PATCH] DocC Improvements (#2111) --- .github/workflows/ios-ci.yml | 8 +- platform/ios/BUILD.bazel | 16 +-- .../ios/Documentation.docc/Documentation.md | 5 - platform/ios/MapLibre.docc/MapLibre.md | 4 + .../ios/MapLibre.docc/theme-settings.json | 20 ++++ platform/ios/bazel/files.bzl | 1 + platform/ios/scripts/docc.sh | 53 ++++++--- platform/ios/src/MLNMapView.h | 103 ++++-------------- .../ios/src/{Mapbox.template.h => Mapbox.h} | 5 - 9 files changed, 94 insertions(+), 121 deletions(-) delete mode 100644 platform/ios/Documentation.docc/Documentation.md create mode 100644 platform/ios/MapLibre.docc/theme-settings.json rename platform/ios/src/{Mapbox.template.h => Mapbox.h} (94%) diff --git a/.github/workflows/ios-ci.yml b/.github/workflows/ios-ci.yml index 0425ac13589..73fc3991f13 100644 --- a/.github/workflows/ios-ci.yml +++ b/.github/workflows/ios-ci.yml @@ -183,17 +183,17 @@ 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' + - name: Build DocC documentation + working-directory: . run: | - scripts/docc.sh + HOSTING_BASE_PATH="maplibre-native/ios/latest" platform/ios/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 + folder: build/docs target-folder: ios/latest/ # Make Metal XCFramework release diff --git a/platform/ios/BUILD.bazel b/platform/ios/BUILD.bazel index 15a7fe0d15b..b0e7f8b9f49 100644 --- a/platform/ios/BUILD.bazel +++ b/platform/ios/BUILD.bazel @@ -31,23 +31,9 @@ filegroup( visibility = ["//visibility:public"], ) -# this can be removed once the legacy renderer is removed completely for iOS -genrule( - name = "umbrella_header", - srcs = ["src/Mapbox.template.h"], - outs = ["src/Mapbox.h"], - cmd = select({ - "//:metal_renderer": """ - echo "#define MLN_RENDER_BACKEND_METAL 1" > $@; - cat $(location src/Mapbox.template.h) >> $@; - """, - "//conditions:default": "cat $(location src/Mapbox.template.h) >> $@", - }), -) - filegroup( name = "ios_public_hdrs", - srcs = MLN_IOS_PUBLIC_HEADERS + [":umbrella_header"], + srcs = MLN_IOS_PUBLIC_HEADERS, visibility = ["//visibility:public"], ) diff --git a/platform/ios/Documentation.docc/Documentation.md b/platform/ios/Documentation.docc/Documentation.md deleted file mode 100644 index 89692a214b4..00000000000 --- a/platform/ios/Documentation.docc/Documentation.md +++ /dev/null @@ -1,5 +0,0 @@ -# ``Mapbox`` - -@Metadata { - @DisplayName("MapLibre Native") -} diff --git a/platform/ios/MapLibre.docc/MapLibre.md b/platform/ios/MapLibre.docc/MapLibre.md index fee157ba388..3be22bc0a3c 100644 --- a/platform/ios/MapLibre.docc/MapLibre.md +++ b/platform/ios/MapLibre.docc/MapLibre.md @@ -15,7 +15,11 @@ Powerful, free and open-source mapping toolkit with full control over data sourc ### Map +- ``MLNSettings`` +- ``MLNMapCamera`` +- ``MLNMapViewDelegate`` - ``MLNMapView`` +- ``MLNUserTrackingMode`` ### Style Layers diff --git a/platform/ios/MapLibre.docc/theme-settings.json b/platform/ios/MapLibre.docc/theme-settings.json new file mode 100644 index 00000000000..29f7ee944a8 --- /dev/null +++ b/platform/ios/MapLibre.docc/theme-settings.json @@ -0,0 +1,20 @@ +{ + "theme": { + "color": { + "documentation-intro-fill": "#111725", + "documentation-intro-accent": "#1058c0", + "link": { + "light": "#1058c0", + "dark": "#82b4fe" + }, + "button-background": { + "light": "#1058c0", + "dark": "#82b4fe" + }, + "fill-blue": { + "light": "#1058c0", + "dark": "#82b4fe" + } + } + } +} diff --git a/platform/ios/bazel/files.bzl b/platform/ios/bazel/files.bzl index fb9ad10976e..3e88047b478 100644 --- a/platform/ios/bazel/files.bzl +++ b/platform/ios/bazel/files.bzl @@ -14,6 +14,7 @@ MLN_IOS_SDK_HEADERS = [ ] MLN_IOS_PUBLIC_HEADERS = [ + "src/Mapbox.h", ] MLN_IOS_PRIVATE_HEADERS = [ diff --git a/platform/ios/scripts/docc.sh b/platform/ios/scripts/docc.sh index ae9a8b389ab..4c8ef3dc8f7 100755 --- a/platform/ios/scripts/docc.sh +++ b/platform/ios/scripts/docc.sh @@ -11,6 +11,9 @@ # $ python3 -m http.server # Go to http://localhost:8000/documentation/maplibre/ +set -e +shopt -s extglob + cmd="convert" if [[ "$1" == "preview" ]]; then cmd="preview" @@ -21,41 +24,65 @@ 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 +rm -rf "$build_dir"/headers mkdir -p "$build_dir"/symbol-graphs -mkdir -p "$build_dir"/headers/MapLibre +mkdir -p "$build_dir"/headers + +bazel build --//:renderer=metal //platform/darwin:generated_style_public_hdrs + +public_headers=$(bazel query 'kind("source file", deps(//platform:ios-sdk, 2))' --output location | grep ".h$" | sed -r 's#.*/([^:]+).*#\1#') +style_headers=$(bazel cquery --//:renderer=metal //platform/darwin:generated_style_public_hdrs --output=files) + +cp $style_headers "$build_dir"/headers + +filter_filenames() { + local prefix="$1" + local filenames="$2" + local filtered_filenames="" + + for filename in $filenames; do + local prefixed_filename="$prefix/$filename" + + if [ -f "$prefixed_filename" ]; then + filtered_filenames="$filtered_filenames $prefixed_filename" + fi + done -# unzip built XCFramework in build dir -unzip ../../bazel-bin/platform/ios/MapLibre.dynamic.xcframework.zip -d "$build_dir" + echo "$filtered_filenames" +} -# copy all public headers from XCFramework -cp "$build_dir"/MapLibre.xcframework/ios-arm64/MapLibre.framework/Headers/*.h "$build_dir"/headers/MapLibre +ios_headers=$(filter_filenames "platform/ios/src" "$public_headers") +darwin_headers=$(filter_filenames "platform/darwin/src" "$public_headers") -xcrun --toolchain swift clang \ +for header in $ios_headers $darwin_headers $style_headers; do + 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 \ + -I platform/darwin/src \ -x objective-c-header \ - -o "$build_dir"/symbol-graphs/MapLibre.symbols.json \ - "$build_dir"/headers/MapLibre/*.h + -o "$build_dir"/symbol-graphs/$(basename $header).symbols.json \ + $header +done export DOCC_HTML_DIR=$(dirname $(xcrun --toolchain swift --find docc))/../share/docc/render -$(xcrun --find docc) "$cmd" MapLibre.docc \ +$(xcrun --find docc) "$cmd" platform/ios/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 \ + --source-service github \ + --source-service-base-url https://github.com/maplibre/maplibre-native/blob/main \ + --checkout-path $(realpath .) \ --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 \ - --hosting-base-path maplibre-native/ios/latest \ # remove for local builds + ${HOSTING_BASE_PATH:+--hosting-base-path "$HOSTING_BASE_PATH"} \ --output-path build/docs fi \ No newline at end of file diff --git a/platform/ios/src/MLNMapView.h b/platform/ios/src/MLNMapView.h index d0daffcca28..292cc6e2edc 100644 --- a/platform/ios/src/MLNMapView.h +++ b/platform/ios/src/MLNMapView.h @@ -72,8 +72,7 @@ typedef NS_ENUM(NSUInteger, MLNOrnamentPosition) { `MLNMapView.userTrackingMode`. #### Related examples - See the - Switch between user tracking modes example to learn how to toggle modes and + - TODO: Switch between user tracking modes example to learn how to toggle modes and how each mode behaves. */ typedef NS_ENUM(NSUInteger, MLNUserTrackingMode) { @@ -145,22 +144,9 @@ FOUNDATION_EXTERN MLN_EXPORT MLNExceptionName const MLNUserLocationAnnotationTyp Mapbox Vector Tile Specification. It styles them with a style that conforms to the MapLibre Style Spec. - Such styles can be designed in - Mapbox Studio and hosted on - mapbox.com. - - A collection of Mapbox-hosted styles is available through the `MLNStyle` - class. These basic styles use - Mapbox Streets - or Mapbox Satellite data - sources, but you can specify a custom style that makes use of your own data. - - Mapbox-hosted vector tiles and styles require an API access token, which you - can obtain from the - Mapbox account page. - Access tokens associate requests to Mapbox’s vector tile and style APIs with - your Mapbox account. They also deter other developers from using your styles - without your permission. + Such styles can be designed with + Maputnik. + Because `MLNMapView` loads asynchronously, several delegate methods are available for receiving map-related updates. These methods can be used to ensure that certain operations @@ -183,10 +169,6 @@ FOUNDATION_EXTERN MLN_EXPORT MLNExceptionName const MLNUserLocationAnnotationTyp @note You are responsible for getting permission to use the map data and for ensuring that your use adheres to the relevant terms of use. - - #### Related examples - See the - Simple map view example to learn how to initialize a basic `MLNMapView`. */ MLN_EXPORT @interface MLNMapView : UIView @@ -213,15 +195,9 @@ MLN_EXPORT @return An initialized map view. #### Related examples - See the - Apply a style designed in Mapbox Studio example to learn how to - initialize an `MLNMapView` with a custom style. See the - Apply a - style designed in Mapbox Studio Classic example to learn how to intialize - an `MLNMapView` with a Studio Classic style _or_ a custom style JSON. See the - Use - third-party vector tiles example to learn how to initialize an - `MLNMapView` with a third-party tile source. + + - TODO: initialize an `MLNMapView` with a custom style + - TODO: how to initialize an `MLNMapView` with a third-party tile source */ - (instancetype)initWithFrame:(CGRect)frame styleURL:(nullable NSURL *)styleURL; @@ -251,13 +227,6 @@ MLN_EXPORT `-[MLNMapViewDelegate mapView:didFinishLoadingStyle:]` or `-[MLNMapViewDelegate mapViewDidFinishLoadingMap:]` method. It is not possible to manipulate the style before it has finished loading. - - @note The default styles provided by Mapbox contain sources and layers with - identifiers that will change over time. Applications that use APIs that - manipulate a style’s sources and layers must first set the style URL to an - explicitly versioned style using a convenience method like - `+[MLNStyle outdoorsStyleURLWithVersion:]`, `MLNMapView`’s “Style URL” - inspectable in Interface Builder, or a manually constructed `NSURL`. */ @property (nonatomic, readonly, nullable) MLNStyle *style; @@ -274,9 +243,7 @@ MLN_EXPORT you want to introspect individual style attributes, use the `style` property. #### Related examples - See the - Switch between map styles example to learn how to change the style of - a map at runtime. + - TODO: change the style of a map at runtime. */ @property (nonatomic, null_resettable) NSURL *styleURL; @@ -284,9 +251,7 @@ MLN_EXPORT Reloads the style. You do not normally need to call this method. The map view automatically - responds to changes in network connectivity by reloading the style. You may - need to call this method if you change the access token after a style has - loaded but before loading a style associated with a different Mapbox account. + responds to changes in network connectivity by reloading the style. This method does not bust the cache. Even if the style has recently changed on the server, calling this method does not necessarily ensure that the map view @@ -364,13 +329,8 @@ MLN_EXPORT @property (nonatomic, assign) CGPoint compassViewMargins; /** - The Mapbox wordmark, positioned in the lower-left corner. - - @note The Mapbox terms of service, which governs the use of Mapbox-hosted - vector tiles and styles, - requires most Mapbox - customers to display the Mapbox wordmark. If this applies to you, do not - hide this view or change its contents. + A logo, the MapLibre logo by default, positioned in the lower-left corner. + You are not required to display this, but some vector-sources may require attribution. */ @property (nonatomic, readonly) UIImageView *logoView; @@ -392,11 +352,8 @@ MLN_EXPORT If you choose to reimplement this view, assign the `-showAttribution:` method as the action for your view to present the default notices and settings. - @note The Mapbox terms of service, which governs the use of Mapbox-hosted - vector tiles and styles, - requires these - copyright notices to accompany any map that features Mapbox-designed styles, - OpenStreetMap data, or other Mapbox data such as satellite or terrain + @note Attribution is often required for many vector sources, + OpenStreetMap data, or other data such as satellite or terrain data. If that applies to this map view, do not hide this view or remove any notices from it. @@ -514,8 +471,7 @@ MLN_EXPORT `-setUserTrackingMode:animated:` method instead. #### Related examples - See the - Customize the user location annotation to learn how to customize the + - TODO: Customize the user location annotation and learn how to customize the default user location annotation shown by `MLNUserTrackingMode`. */ @property (nonatomic, assign) MLNUserTrackingMode userTrackingMode; @@ -1143,9 +1099,7 @@ MLN_EXPORT immediately. #### Related examples - See the - Camera animation example to learn how to trigger an animation that - rotates around a central point. + - TODO: Camera animation: learn how to trigger an animation that rotates around a central point. */ - (void)setCamera:(MLNMapCamera *)camera animated:(BOOL)animated; @@ -1163,8 +1117,7 @@ MLN_EXPORT is `0`, this parameter is ignored. #### Related examples - See the - Camera animation example to learn how to create a timed animation that + - TODO: Camera animation: learn how to create a timed animation that rotates around a central point for a specific duration. */ - (void)setCamera:(MLNMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function; @@ -1483,9 +1436,7 @@ MLN_EXPORT @return The geographic coordinate at the given point. #### Related examples - See the - Point conversion example to learn how to convert a `CGPoint` to a map - coordinate. + - TODO: Point conversion example to learn how to convert a `CGPoint` to a map coordinate. */ - (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(nullable UIView *)view; @@ -1502,9 +1453,7 @@ MLN_EXPORT corresponding to the given geographic coordinate. #### Related examples - See the - Point conversion example to learn how to convert a map coordinate to a - `CGPoint` object. + - TODO: Point conversion: learn how to convert a map coordinate to a `CGPoint` object. */ - (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable UIView *)view; @@ -1583,10 +1532,8 @@ MLN_EXPORT annotation object. #### Related examples - See the - Annotation models and - Add a line annotation from GeoJSON examples to learn how to add an - annotation to an `MLNMapView` object. + - TODO: add a line annotation from GeoJSON. + - TODO: add an annotation to an `MLNMapView` object. */ - (void)addAnnotation:(id )annotation; @@ -1654,8 +1601,7 @@ MLN_EXPORT such object exists in the reuse queue. #### Related examples - See the - Add annotation views and images example learn how to most efficiently + - TODO: Add annotation views and images: learn how to most efficiently reuse an `MLNAnnotationImage`. */ - (nullable __kindof MLNAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier; @@ -1847,8 +1793,7 @@ MLN_EXPORT represent features in the sources used by the current style. #### Related examples - See the - Select a feature within a layer example to learn how to query an + - TODO: Select a feature within a layer: to learn how to query an `MLNMapView` object for visible `MLNFeature` objects. */ - (NSArray> *)visibleFeaturesAtPoint:(CGPoint)point NS_SWIFT_NAME(visibleFeatures(at:)); @@ -1909,7 +1854,7 @@ MLN_EXPORT point, even if the road extends into other tiles. To find out the layer names in a particular style, view the style in - Mapbox Studio. + Maputnik. Only visible features are returned. To obtain features regardless of visibility, use the @@ -2012,7 +1957,7 @@ MLN_EXPORT the road within each map tile is included individually. To find out the layer names in a particular style, view the style in - Mapbox Studio. + Maputnik. Only visible features are returned. To obtain features regardless of visibility, use the diff --git a/platform/ios/src/Mapbox.template.h b/platform/ios/src/Mapbox.h similarity index 94% rename from platform/ios/src/Mapbox.template.h rename to platform/ios/src/Mapbox.h index bd74eb2ceca..076b7f6f95d 100644 --- a/platform/ios/src/Mapbox.template.h +++ b/platform/ios/src/Mapbox.h @@ -46,9 +46,6 @@ FOUNDATION_EXPORT MLN_EXPORT const unsigned char MapboxVersionString[]; #import "MLNOfflinePack.h" #import "MLNOfflineRegion.h" #import "MLNOfflineStorage.h" -#if !MLN_RENDER_BACKEND_METAL -#import "MLNOpenGLStyleLayer.h" -#endif #import "MLNOverlay.h" #import "MLNPointAnnotation.h" #import "MLNPointCollection.h" @@ -77,6 +74,4 @@ FOUNDATION_EXPORT MLN_EXPORT const unsigned char MapboxVersionString[]; #import "NSPredicate+MLNAdditions.h" #import "NSValue+MLNAdditions.h" #import "MLNUserLocationAnnotationViewStyle.h" -#if defined(MLN_DRAWABLE_RENDERER) || defined(MLN_RENDER_BACKEND_METAL) #import "MLNCustomDrawableStyleLayer.h" -#endif