Merge pull request #36 from appdevforall/fix/ADFA-5548

ADFA-5548: Android(X) docs in template format

Author: alexmmiller

.github/workflows/build-android-docs-local.yaml

@@ -47,8 +47,10 @@ permissions:
 
 # This workflow overwrites a single shared Drive file - never let two runs
 # race to upload against each other.
+# Shared with build-android-docs.yaml: both rewrite the same documentation.db on Drive, so they
+# have to serialise against each other, not merely against a second run of themselves.
 concurrency:
-  group: build-kotlin-docs
+  group: documentation-db
   cancel-in-progress: false
 
 on:

.github/workflows/build-android-docs.yaml

@@ -0,0 +1,3 @@
+# Gradle build output.
+build/
+.gradle/

.github/workflows/build-kotlin-docs.yaml

@@ -0,0 +1,42 @@
+// Renders the JSON that android_docs_to_json.py writes into browsable HTML, using Pebble
+// templates that follow the layout of the reference pages the JSON was read from.
+//
+// Deliberately plain Java, and compiled for 17 rather than through a toolchain: this has to build
+// with whatever JDK happens to be on the machine, and nothing here needs anything newer.
+plugins {
+    application
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation("io.pebbletemplates:pebble:3.2.2")
+    implementation("com.fasterxml.jackson.core:jackson-databind:2.17.2")
+
+    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
+}
+
+// The templates are the part of this module most likely to break silently: Pebble is configured
+// with strictVariables(false), so a field that stops existing renders as nothing rather than as
+// an error, and a macro called with a `macros.` prefix renders empty too. The tests render a real
+// page and assert the pieces are there.
+tasks.test {
+    useJUnitPlatform()
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
+
+application {
+    mainClass.set("org.appdevforall.docs.android.AndroidDocRenderer")
+}
+
+tasks.named<JavaExec>("run") {
+    // Lets the driver script pass "<json-dir> <html-dir>" through as -Pargs="..."
+    (findProperty("args") as String?)?.let { args = it.split(" ").filter { a -> a.isNotEmpty() } }
+}

ProcessDocs/AndroidDocs/AndroidDocsToJson/README.md

@@ -0,0 +1,9 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.5.1-bin.zip
+networkTimeout=10000
+retries=0
+retryBackOffMs=500
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists