Use Mustache to add component and tokens versions in documentation

Author: florentmaitre

.gitignore

@@ -36,3 +36,6 @@ docs/dokka/
 
 # App
 app/src/main/res/raw/changelog.md
+
+# Mustache output
+Module.md

app/build.gradle.kts

@@ -168,7 +168,6 @@ fun updateBuildConfig() {
 gradle.projectsEvaluated {
     tasks["preBuild"].apply {
         dependsOn(":checkNotice")
-        dependsOn(":checkTokensVersion")
         dependsOn(tasks["updateAppChangelog"])
     }
     updateBuildConfig()

build.gradle.kts

@@ -24,7 +24,6 @@ plugins {
     id("release")
     id("netlify")
     id("check-notice")
-    id("tokens-version")
 }
 
 dependencies {

buildSrc/build.gradle.kts

@@ -42,7 +42,17 @@ dependencies {
     implementation(libs.javapoet) // https://github.com/google/dagger/issues/3282
     implementation(libs.json)
     implementation(libs.kotlin.gradle.plugin) // https://issuetracker.google.com/issues/176079157#comment14
-    implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location)) // https://github.com/gradle/gradle/issues/15383
+    implementation(libs.mustache.java)
     implementation(libs.zxing.core)
     implementation(libs.zxing.javase)
+    implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location)) // https://github.com/gradle/gradle/issues/15383
+}
+
+sourceSets {
+    named("main") {
+        java {
+            srcDir("../theme-contract/src/main/java")
+            setIncludes(listOf("com/orange/ouds/theme/OudsVersion.kt"))
+        }
+    }
 }

buildSrc/src/main/kotlin/documentation.gradle.kts

@@ -0,0 +1,57 @@
+/*
+ * Software Name: OUDS Android
+ * SPDX-FileCopyrightText: Copyright (c) Orange SA
+ * SPDX-License-Identifier: MIT
+ *
+ * This software is distributed under the MIT license,
+ * the text of which is available at https://opensource.org/license/MIT/
+ * or see the "LICENSE" file for more details.
+ *
+ * Software description: Android library of reusable graphical components
+ */
+
+import com.github.mustachejava.DefaultMustacheFactory
+import java.io.FileOutputStream
+import java.io.PrintWriter
+import kotlin.reflect.full.declaredMemberProperties
+
+tasks.register<DefaultTask>("prepareDocumentation") {
+    doLast {
+        val mustacheFactory = DefaultMustacheFactory()
+
+        // Retrieve OudsVersion.Component object and fill the table in core/Module.md with the component design versions
+        val coreModuleDocumentationWriter = PrintWriter(FileOutputStream("core/Module.md"))
+        // Build a map in order to loop through all component versions in core Module.mustache
+        val componentVersions = Class.forName("com.orange.ouds.theme.OudsVersion${'$'}Component")
+            .kotlin
+            .declaredMemberProperties
+            .map { property ->
+                val name = property.name
+                    .split("(?=\\p{Upper})".toRegex())
+                    .filter { it.isNotEmpty() }
+                    .mapIndexed { index, word -> if (index == 0) word else word.lowercase() }
+                    .joinToString(" ")
+                val value = property.getter.call() as String
+                mapOf("name" to name, "value" to value)
+            }
+        mustacheFactory.compile("core/Module.mustache")
+            .execute(coreModuleDocumentationWriter, mapOf("versions" to componentVersions))
+            .flush()
+
+        // Retrieve OudsVersion.Tokens object and fill the tokens versions in various Module.md files
+        val moduleDocumentationDirectories = listOf(
+            "global-raw-tokens",
+            "theme-contract",
+            "theme-orange",
+            "theme-sosh"
+        )
+        // Use OudsVersion.Tokens directly in various Module.mustache files
+        val tokensVersions = Class.forName("com.orange.ouds.theme.OudsVersion${'$'}Tokens").kotlin.objectInstance
+        moduleDocumentationDirectories.forEach { moduleDocumentationDirectory ->
+            val moduleDocumentationWriter = PrintWriter(FileOutputStream("$moduleDocumentationDirectory/Module.md"))
+            mustacheFactory.compile("$moduleDocumentationDirectory/Module.mustache")
+                .execute(moduleDocumentationWriter, tokensVersions)
+                .flush()
+        }
+    }
+}

buildSrc/src/main/kotlin/dokka.gradle.kts

@@ -12,6 +12,7 @@
 
 plugins {
     id("org.jetbrains.dokka")
+    id("documentation")
 }
 
 dokka {
@@ -30,3 +31,8 @@ dokka {
         failOnWarning.set(true)
     }
 }
+
+gradle.projectsEvaluated {
+    tasks["dokkaGenerate"].dependsOn(tasks["prepareDocumentation"]) // Case where dokkaGenerate is called from the subproject
+    tasks["dokkaGenerateModuleHtml"].dependsOn(tasks["prepareDocumentation"]) // Case where dokkaGenerate is called from the root project
+}

buildSrc/src/main/kotlin/tokens-version.gradle.kts

@@ -2,6 +2,14 @@
 
 Contains the main elements of the OUDS Android library.
 
+The table below lists the design version of each component:
+
+| Component | Design version |
+| :--- | ---: |
+{{#versions}}
+| {{name}} | {{value}} |
+{{/versions}}
+
 # Package com.orange.ouds.core.component
 
 Contains all OUDS basic components: OudsButton, OudsLink,...

core/Module.md core/Module.mustachecore/Module.md renamed to core/Module.mustache

@@ -1,7 +1,8 @@
 # Module global-raw-tokens
 
 ```
-Tokens version 1.2.0
+Android core tokens version {{AndroidCore}}
+OUDS core tokens version {{OudsCore}}
 ```
 
 Contains the raw tokens that can be used by any theme.

global-raw-tokens/Module.md global-raw-tokens/Module.mustacheglobal-raw-tokens/Module.md renamed to global-raw-tokens/Module.mustache

@@ -25,6 +25,7 @@ kotlin = "2.2.0"
 material = "1.12.0"
 mockitoAndroid = "5.18.0"
 mockitoKotlin = "6.0.0"
+mustacheJava = "0.9.14"
 navigationCompose = "2.9.2"
 paparazzi = "1.3.5"
 zxing = "3.5.3"
@@ -68,6 +69,7 @@ kotlin-reflect = { group = "org.jetbrains.kotlin", name = "kotlin-reflect", vers
 material = { group = "com.google.android.material", name = "material", version.ref = "material" }
 mockito-android = { group = "org.mockito", name = "mockito-android", version.ref = "mockitoAndroid" }
 mockito-kotlin = { group = "org.mockito.kotlin", name = "mockito-kotlin", version.ref = "mockitoKotlin" }
+mustache-java = { module = "com.github.spullara.mustache.java:compiler", version.ref = "mustacheJava" }
 zxing-core = { module = "com.google.zxing:core", version.ref = "zxing" }
 zxing-javase = { module = "com.google.zxing:javase", version.ref = "zxing" }