Add iOS Getting Started Guide to DocC (#2384)

.github/workflows/gh-pages-docc.yml

@@ -1,24 +0,0 @@
-name: gh-pages-docc
-
-on:
-  workflow_dispatch:
-
-jobs:
-  gh-pages-docc:
-    defaults:
-      run:
-        working-directory: platform/ios
-    runs-on: [self-hosted, macOS, ARM64]
-    steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
-
-      - name: Generate documentation
-        run: make ios-docs
-
-      - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@v4.6.0
-        with:
-          branch: gh-pages
-          folder: platform/ios/build/ios/static-docs
-          target-folder: docs/ios/docc/

platform/ios/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Documentation
+
+We use [DocC](https://www.swift.org/documentation/docc) for documentation. To build the documentation locally, run the following command from the root directory of the repository:
+
+```
+platform/ios/scripts/docc.sh preview
+```
+
+You need to have [aws-cli](https://github.com/aws/aws-cli) installed to download the resources from S3 (see below).
+
+## Resources
+
+Resources like images should not be checked in but should be uploaded to the [S3 Bucket](https://s3.eu-central-1.amazonaws.com/maplibre-native/index.html#ios-documentation-resources/). You can share a `.zip` with all files that should be added in the PR.
+
+If you want to get direct access you need an AWS account to get permissions to upload files. Create an account and authenticate with aws-cli. Share account's ARN that you can get with
+
+```
+aws sts get-caller-identity
+```
+
+When the needed resources are uploaded the filenames need to be added to the `resources` array in `platform/ios/scripts/docc.sh`.
+
+```bash
+resources=(
+  "AddPackageDependencies@2x.png"
+  # ...
+  # add here
+)
+```

platform/ios/MapLibre.docc/GettingStarted.md

@@ -0,0 +1,58 @@
+# Getting Started
+
+Setting up an Xcode project that uses MapLibre Native for iOS.
+
+## Create a new iOS project
+
+Create a new (SwiftUI) iOS project with Xcode. Go to *File > New > Project...*.
+
+## Add MapLibre Native as a dependency
+
+MapLibre Native for iOS is available on [Cocoapods](https://cocoapods.org) and on the [Swift Package Index](https://swiftpackageindex.com/maplibre/maplibre-gl-native-distribution) (for use with the Swift Package Manager). However, for this guide we will add the MapLibre Native as a package dependency directly.
+
+In Xcode, right click your project and select "Add Package Dependencies...":
+
+![](AddPackageDependencies.png)
+
+Paste the following URL and click Add Package:
+
+```
+https://github.com/maplibre/maplibre-gl-native-distribution
+```
+
+> Note: The [maplibre-gl-native-distributon](https://github.com/maplibre/maplibre-gl-native-distribution) repository only exists for distributing the iOS package of MapLibre Native. To report issues and ask questions, use the [maplibre-native](https://github.com/maplibre/maplibre-native) repository.
+
+Verify you can import MapLibre in your app:
+
+```swift
+import MapLibre
+```
+
+To use MapLibre with SwiftUI we need to create a wrapper for the UIKit view that MapLibre provides (using UIViewRepresentable. The simplest way to implement this protocol is as follows:
+
+```swift
+struct MapLibreMapView: UIViewRepresentable {
+    private let mapView = MLNMapView()
+    
+    func makeUIView(context: Context) -> some UIView {
+        return mapView
+    }
+    
+    func updateUIView(_ uiView: UIViewType, context: Context) {
+    }
+}
+```
+
+You can use this view directly in a SwiftUI View hierarcy, for example:
+
+```swift
+struct ContentView: View {
+    var body: some View {
+        MapLibreMapView()
+    }
+}
+```
+
+When running your app in the simulator you should be greeted with the default [Demotiles](https://demotiles.maplibre.org/) style:
+
+![](DemotilesScreenshot.png)

platform/ios/MapLibre.docc/MapLibre.md

@@ -11,6 +11,10 @@ Powerful, free and open-source mapping toolkit with full control over data sourc
 [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/).
 
+## Essentials
+
+- <doc:GettingStarted>
+
 ## Topics
 
 ### Map

platform/ios/MapLibre.docc/Resources/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

platform/ios/scripts/docc.sh

@@ -4,7 +4,7 @@
 # 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:
-# $ platform/ios/scripts/docc.sh bazel
+# $ platform/ios/scripts/docc.sh preview
 # You can also build the documentation locally
 # $ platform/ios/scripts/docc.sh
 # Then go to build/MapLibre.doccarchive and run
@@ -31,6 +31,23 @@ mkdir -p "$build_dir"/headers
 
 bazel build --//:renderer=metal //platform/darwin:generated_style_public_hdrs
 
+# download resources from S3
+
+resources=(
+  "AddPackageDependencies@2x.png"
+  "DemotilesScreenshot@2x.png"
+)
+
+destination_dir="platform/ios/MapLibre.docc/Resources"
+
+for file in "${resources[@]}"; do
+  if [[ ! -f "$destination_dir/$file" ]]; then
+    aws s3 cp --no-sign-request "s3://maplibre-native/ios-documentation-resources/$file" "$destination_dir"
+  else
+    echo "Skipped: $file already exists in the destination directory"
+  fi
+done
+
 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)