DocC Improvements (#2111)

2024-02-14 11:09:22 +01:00
parent 8e5fc4c198
commit 17e6e7cdcb
9 changed files with 93 additions and 120 deletions
--- 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
--- 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"],
 )

--- a/platform/ios/Documentation.docc/Documentation.md
+++ b/platform/ios/Documentation.docc/Documentation.md
@@ -1,5 +0,0 @@
-# ``Mapbox``
-
-@Metadata {
-    @DisplayName("MapLibre Native")
-}
--- 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

--- a/platform/ios/MapLibre.docc/theme-settings.json
+++ 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"
+      }
+    }
+  }
+}
--- 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 = [
--- 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

-# unzip built XCFramework in build dir
-unzip ../../bazel-bin/platform/ios/MapLibre.dynamic.xcframework.zip -d "$build_dir"
+bazel build --//:renderer=metal //platform/darwin:generated_style_public_hdrs

-# copy all public headers from XCFramework
-cp "$build_dir"/MapLibre.xcframework/ios-arm64/MapLibre.framework/Headers/*.h "$build_dir"/headers/MapLibre
+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)

-xcrun --toolchain swift clang \
+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
+
+    echo "$filtered_filenames"
+}
+
+ios_headers=$(filter_filenames "platform/ios/src" "$public_headers")
+darwin_headers=$(filter_filenames "platform/darwin/src" "$public_headers")
+
+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
--- 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 <a href="https://docs.mapbox.com/ios/maps/examples/user-tracking-mode/">
- Switch between user tracking modes</a> example to learn how to toggle modes and
+ - TODO: Switch between user tracking modes</a> 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
 <a href="https://github.com/mapbox/vector-tile-spec">Mapbox Vector Tile Specification</a>.
 It styles them with a style that conforms to the
 <a href="https://maplibre.org/maplibre-style-spec/">MapLibre Style Spec</a>.
- Such styles can be designed in
- <a href="https://www.mapbox.com/studio/">Mapbox Studio</a> and hosted on
- mapbox.com.
+ Such styles can be designed with
+ <a href="https://maplibre.org/maputnik/">Maputnik</a>.

- A collection of Mapbox-hosted styles is available through the `MLNStyle`
- class. These basic styles use
- <a href="https://www.mapbox.com/developers/vector-tiles/mapbox-streets">Mapbox Streets</a>
- or <a href="https://www.mapbox.com/satellite/">Mapbox Satellite</a> 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
- <a href="https://www.mapbox.com/studio/account/tokens/">Mapbox account page</a>.
- 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.

 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 <a href="https://docs.mapbox.com/ios/maps/examples/simple-map-view/">
- Simple map view</a> example to learn how to initialize a basic `MLNMapView`.
 */
 MLN_EXPORT
@interface MLNMapView : UIView <MLNStylable>
@@ -213,15 +195,9 @@ MLN_EXPORT
 @return An initialized map view.

 #### Related examples
- See the <a href="https://docs.mapbox.com/ios/maps/examples/custom-style/">
- Apply a style designed in Mapbox Studio</a> example to learn how to
- initialize an `MLNMapView` with a custom style. See the
- <a href="https://docs.mapbox.com/ios/maps/examples/raster-styles/"> Apply a
- style designed in Mapbox Studio Classic</a> example to learn how to intialize
- an `MLNMapView` with a Studio Classic style _or_ a custom style JSON. See the
- <a href="https://docs.mapbox.com/ios/maps/examples/source-custom-vector/"> Use
- third-party vector tiles</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/switch-styles/">
- Switch between map styles</a> 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,
-    <a href="https://docs.mapbox.com/help/how-mapbox-works/attribution/">requires</a> 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,
-    <a href="https://www.mapbox.com/tos/#[FamaFama]">requires</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/user-location-annotation/">
- Customize the user location annotation</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/camera-animation/">
- Camera animation</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/camera-animation/">
- Camera animation</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/point-conversion/">
- Point conversion</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/point-conversion/">
- Point conversion</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/annotation-models/">
- Annotation models</a> and <a href="https://docs.mapbox.com/ios/maps/examples/line-geojson/">
- Add a line annotation from GeoJSON</a> 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 <MLNAnnotation>)annotation;

@@ -1654,8 +1601,7 @@ MLN_EXPORT
    such object exists in the reuse queue.

 #### Related examples
- See the <a href="https://docs.mapbox.com/ios/maps/examples/annotation-view-image/">
- Add annotation views and images</a> 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 <a href="https://docs.mapbox.com/ios/maps/examples/select-layer/">
- Select a feature within a layer</a> 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<id <MLNFeature>> *)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
- <a href="https://www.mapbox.com/studio/">Mapbox Studio</a>.
+ <a href="https://maplibre.org/maputnik">Maputnik</a>.

 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
- <a href="https://www.mapbox.com/studio/">Mapbox Studio</a>.
+ <a href="https://maplibre.org/maputnik">Maputnik</a>.

 Only visible features are returned. To obtain features regardless of
 visibility, use the
--- a/platform/ios/src/Mapbox.template.h
+++ b/platform/ios/src/Mapbox.template.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