Split out Android examples to separate documentation site (#2978)

.github/workflows/android-ci.yml

@@ -143,8 +143,11 @@ jobs:
       - name: Build libmaplibre.so for arm-v8
         run: make android-lib-arm-v8
 
-      - name: Build documentation
+      - name: Build API documentation
         run: ./gradlew dokkaHtml
+
+      - name: Build Examples documentation
+        run: make mkdocs-build
 
       - name: Copy developer config with API key for UI tests
         if: github.ref == 'refs/heads/main'

.github/workflows/gh-pages-android-examples.yml

@@ -0,0 +1,30 @@
+name: gh-pages-android-examples
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'platform/android/**'
+
+jobs:
+  gh-pages-android-examples:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: platform/android
+        shell: bash
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Generate documentation
+        run: make mkdocs-build
+
+      - name: Deploy 🚀
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: platform/android/site
+          target-folder: maplibre-native/android/examples/

.gitignore

@@ -41,6 +41,7 @@ compile_commands.json
 /platform/ios/platform/ios/benchmark/assets/glyphs/Roboto Condensed Italic,Noto Sans Italic
 /platform/ios/platform/ios/benchmark/assets/glyphs/Noto Sans Regular
 /platform/android/key.json
+/platform/android/site
 node_modules
 # Node binaries.
 /lib

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
     rev: v5.0.0
     hooks:
     -   id: check-yaml
-        args: [--allow-multiple-documents]
+        args: [--allow-multiple-documents, --unsafe]
 - repo: https://github.com/pre-commit/mirrors-clang-format
   rev: v19.1.3
   hooks:

platform/android/DEVELOPING.md

@@ -92,3 +92,16 @@ To run the benchmarks (for Android) include the following line on a PR comment:
 ## Profiling
 
 [maplibre-native/docs/mdbook](https://maplibre.org/maplibre-native/docs/book/) describes how Tracy can be used for profiling.
+
+
+## Examples Documentation
+
+To build the Examples Documentation you need to have Docker installed.
+
+From `platform/android`, run:
+
+```
+make mkdocs
+```
+
+Next, visit http://localhost:8000/maplibre-native/android/examples/

platform/android/Makefile

@@ -311,3 +311,13 @@ clean:
 	        ./MapLibreAndroidTestApp/src/androidTest/java/org/maplibre/android/testapp/activity/gen \
 	        ./MapLibreAndroid/src/main/assets \
 		    ./MapLibreAndroidTestApp/src/main/assets/integration
+
+### MkDocs Documentation ########################################################
+
+.PHONY: mkdocs
+mkdocs:
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+
+.PHONY: mkdocs-build
+mkdocs-build:
+	docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build --strict

platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/attribution/AttributionParser.java

@@ -65,6 +65,9 @@ public String createAttributionString() {
    */
   @NonNull
   public String createAttributionString(boolean shortenedOutput) {
+    if (attributions.isEmpty()) {
+      return "";
+    }
     StringBuilder stringBuilder = new StringBuilder(withCopyrightSign ? "" : "© ");
     int counter = 0;
     for (Attribution attribution : attributions) {

platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/snapshotter/MapSnapshotter.kt

@@ -2,6 +2,7 @@ package org.maplibre.android.snapshotter
 
 import android.content.Context
 import android.graphics.*
+import android.os.Build
 import android.os.Handler
 import android.os.Looper
 import android.text.Html
@@ -515,15 +516,7 @@ open class MapSnapshotter(context: Context, options: Options) {
             drawAttribution(canvas, measure, anchorPoint)
         } else {
             val snapshot = mapSnapshot.bitmap
-            Logger.e(
-                TAG,
-                String.format(
-                    "Could not generate attribution for snapshot size: %s x %s." + " You are required to provide your own attribution for the used sources: %s",
-                    snapshot.width,
-                    snapshot.height,
-                    mapSnapshot.attributions
-                )
-            )
+            Logger.e(TAG, "Could not generate attribution for snapshot size: ${snapshot.width} x ${snapshot.height}. You are required to provide your own attribution for the used sources: ${mapSnapshot.attributions.joinToString()}")
         }
     }
 
@@ -544,7 +537,17 @@ open class MapSnapshotter(context: Context, options: Options) {
         textView.textSize = 10 * scale
         textView.setTextColor(textColor)
         textView.setBackgroundResource(R.drawable.maplibre_rounded_corner)
-        textView.text = Html.fromHtml(createAttributionString(mapSnapshot, shortText))
+        val attributionString = createAttributionString(mapSnapshot, shortText)
+        if (attributionString == "") {
+            Logger.w(
+                TAG,
+                String.format(
+                    "Attribution string is empty. Make sure you provide your own attribution for the used sources if needed.",
+                )
+            )
+            return TextView(context)
+        }
+        textView.text = fromHTML(attributionString)
         textView.measure(widthMeasureSpec, heightMeasureSpec)
         textView.layout(0, 0, textView.measuredWidth, textView.measuredHeight)
         return textView
@@ -770,3 +773,9 @@ open class MapSnapshotter(context: Context, options: Options) {
         private const val LOGO_MARGIN_DP = 4
     }
 }
+
+fun fromHTML(source: String) = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+    Html.fromHtml(source, Html.FROM_HTML_MODE_LEGACY)
+} else {
+    Html.fromHtml(source)
+}

platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/attribution/AttributionParseTest.kt

@@ -362,6 +362,21 @@ class AttributionParseTest {
         )
     }
 
+    @Test
+    @Throws(Exception::class)
+    fun testOutputNoAttribution() {
+        val attributionParser = AttributionParser.Options(RuntimeEnvironment.application)
+            .withAttributionData("")
+            .withCopyrightSign(false)
+            .withImproveMap(false)
+            .build()
+        Assert.assertEquals(
+            "Attribution string should match",
+            "",
+            attributionParser.createAttributionString()
+        )
+    }
+
     companion object {
         private const val STREETS_ATTRIBUTION =
             "<a href=\"https://www.mapbox.com/about/maps/\" target=\"_blank\">&copy; MapLibre</a> <a href=\"http://www.openstreetmap.org/about/\" target=\"_blank\">&copy; OpenStreetMap</a> \n"

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/annotation/JsonApiActivity.kt

@@ -27,15 +27,15 @@ import java.io.IOException
 import java.text.SimpleDateFormat
 import java.util.Locale
 
-/* ANCHOR: top */
+// # --8<-- [start:top]
 class JsonApiActivity : AppCompatActivity() {
 
     // Declare a variable for MapView
     private lateinit var mapView: MapView
 
     // Declare a variable for MapLibreMap
     private lateinit var maplibreMap: MapLibreMap
-    /* ANCHOR_END: top */
+    // # --8<-- [end:top]
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -48,7 +48,7 @@ class JsonApiActivity : AppCompatActivity() {
         // Init the MapView
         mapView = findViewById(R.id.mapView)
 
-        /* ANCHOR: mapAsync */
+        // # --8<-- [start:mapAsync]
         mapView.getMapAsync { map ->
             maplibreMap = map
 
@@ -57,10 +57,10 @@ class JsonApiActivity : AppCompatActivity() {
             // Fetch data from USGS
             getEarthQuakeDataFromUSGS()
         }
-        /* ANCHOR_END: mapAsync */
+        // # --8<-- [end:mapAsync]
     }
 
-    /* ANCHOR: getEarthquakes */
+    // # --8<-- [start:getEarthquakes]
     // Get Earthquake data from usgs.gov, read API doc at:
     // https://earthquake.usgs.gov/fdsnws/event/1/
     private fun getEarthQuakeDataFromUSGS() {
@@ -91,9 +91,9 @@ class JsonApiActivity : AppCompatActivity() {
             }
         })
     }
-    /* ANCHOR_END: getEarthquakes */
+    // # --8<-- [end:getEarthquakes]
 
-    /* ANCHOR: addMarkers */
+    // # --8<-- [start:addMarkers]
     private fun addMarkersToMap(data: FeatureCollection) {
         val bounds = mutableListOf<LatLng>()
 
@@ -146,7 +146,7 @@ class JsonApiActivity : AppCompatActivity() {
             maplibreMap.cameraPosition = newCameraPosition
         }
     }
-    /* ANCHOR_END: addMarkers */
+    // # --8<-- [end:addMarkers]
 
     override fun onStart() {
         super.onStart()

platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/camera/GestureDetectorActivity.kt

@@ -110,6 +110,7 @@ class GestureDetectorActivity : AppCompatActivity() {
     }
 
     fun attachListeners() {
+        // # --8<-- [start:addOnMoveListener]
         maplibreMap.addOnMoveListener(
             object : OnMoveListener {
                 override fun onMoveBegin(detector: MoveGestureDetector) {
@@ -132,6 +133,7 @@ class GestureDetectorActivity : AppCompatActivity() {
                 }
             }
         )
+        // # --8<-- [end:addOnMoveListener]
         maplibreMap.addOnRotateListener(
             object : OnRotateListener {
                 override fun onRotateBegin(detector: RotateGestureDetector) {