chore: include design component version in dev documentation (#661)

* Add version screen in about

* Add component version in demo screens

* Use Mustache to add component and tokens versions in documentation

* Add a Dokka plugin to display the component design version and guidelines URL in documentation

* Display design guidelines and version in a table instead of two separate sections

* Simplify code by removing OudsComponentTagContentProvider

* Fix "Duplicate content roots detected" error

* Add Gradle tasks to check and update documentation

* Fix Gradle sync issue

* Tokens versions are now displayed in a table

* Document code related to Dokka plugin

* Update CSS to always wrap composable parameters in the documentation

* Review: Replace values with entries

* Review: Remove useless context property in OudsComponentDocumentableTransformer

* Review: Add documentation explaining the purpose of OudsDokkaPlugin

---------

Co-authored-by: Pauline Auvray <[email protected]>

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

@@ -150,8 +150,6 @@ tasks.register<DefaultTask>("updateAppChangelog") {
 }
 
 fun updateBuildConfig() {
-    val tokensVersion = findTypedProperty<String>("tokensVersion").orEmpty()
-
     val gitHubWorkflow = Environment.getVariablesOrNull("GITHUB_WORKFLOW").first()
     val pullRequestNumber = if (gitHubWorkflow == "app-distribution-alpha") {
         gitHubApi {
@@ -163,15 +161,14 @@ fun updateBuildConfig() {
     }
 
     android.defaultConfig {
-        buildConfigField("String", "TOKENS_VERSION", "\"$tokensVersion\"")
         buildConfigField("String", "PULL_REQUEST_NUMBER", if (pullRequestNumber != null) "\"$pullRequestNumber\"" else "null")
     }
 }
 
 gradle.projectsEvaluated {
     tasks["preBuild"].apply {
+        dependsOn(":checkDocumentation")
         dependsOn(":checkNotice")
-        dependsOn(":checkTokensVersion")
         dependsOn(tasks["updateAppChangelog"])
     }
     updateBuildConfig()

app/src/main/java/com/orange/ouds/app/ui/Screen.kt

@@ -116,4 +116,9 @@ sealed class Screen(
         route = AboutDestinations.MaterialComponentsRoute,
         title = R.string.app_about_materialComponents_label
     )
+
+    data object AboutVersions : Screen(
+        route = AboutDestinations.VersionsRoute,
+        title = R.string.app_about_versions_label
+    )
 }

app/src/main/java/com/orange/ouds/app/ui/about/AboutNavigation.kt

@@ -21,6 +21,7 @@ import com.orange.ouds.app.ui.about.AboutNavigationKey.MenuItemIdKey
 object AboutDestinations {
     const val FileRoute = "ouds/module/about/file"
     const val MaterialComponentsRoute = "ouds/module/about/materialComponents"
+    const val VersionsRoute = "ouds/module/about/versions"
 }
 
 object AboutNavigationKey {
@@ -40,4 +41,8 @@ fun NavGraphBuilder.addAboutNavGraph() {
     composable(AboutDestinations.MaterialComponentsRoute) { _ ->
         AboutMaterialComponentsScreen()
     }
+
+    composable(AboutDestinations.VersionsRoute) { _ ->
+        AboutVersionsScreen()
+    }
 }

app/src/main/java/com/orange/ouds/app/ui/about/AboutScreen.kt

@@ -47,8 +47,9 @@ private val oudsAboutMenuItems = listOf(
     AboutFileMenuItem(1, R.string.app_about_legalInformation_label, AboutFileMenuItem.File(R.raw.about_legal_information, AboutFileMenuItem.File.Format.Html)),
     AboutFileMenuItem(2, R.string.app_about_privacyPolicy_label, AboutFileMenuItem.File(R.raw.about_privacy_policy, AboutFileMenuItem.File.Format.Html)),
     AboutFileMenuItem(3, R.string.app_about_changelog_label, AboutFileMenuItem.File(R.raw.changelog, AboutFileMenuItem.File.Format.Markdown)),
-    AboutRouteMenuItem(4, R.string.app_about_materialComponents_label, AboutDestinations.MaterialComponentsRoute),
-    AboutAppSettingsItem(5, R.string.app_about_changeLanguage_label)
+    AboutRouteMenuItem(4, R.string.app_about_versions_label, AboutDestinations.VersionsRoute),
+    AboutRouteMenuItem(5, R.string.app_about_materialComponents_label, AboutDestinations.MaterialComponentsRoute),
+    AboutAppSettingsItem(6, R.string.app_about_changeLanguage_label)
 )
 
 sealed class AboutMenuItem(val id: Int, @StringRes val labelRes: Int) {
@@ -97,10 +98,6 @@ fun AboutScreen(onMenuItemClick: (id: Int) -> Unit) {
                                 }
                                 Text(text = pullRequest, style = OudsTheme.typography.body.default.medium)
                             }
-                            Text(
-                                text = stringResource(R.string.app_about_tokensVersion_label, BuildConfig.TOKENS_VERSION),
-                                style = OudsTheme.typography.body.default.medium
-                            )
                         }
                     }
                 )

app/src/main/java/com/orange/ouds/app/ui/about/AboutVersionsScreen.kt

@@ -0,0 +1,106 @@
+/*
+ * 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
+ */
+
+package com.orange.ouds.app.ui.about
+
+import androidx.annotation.StringRes
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material3.ListItem
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.tooling.preview.PreviewLightDark
+import com.orange.ouds.app.R
+import com.orange.ouds.app.ui.utilities.composable.Screen
+import com.orange.ouds.app.ui.utilities.listItemHorizontalPadding
+import com.orange.ouds.core.theme.OudsTheme
+import com.orange.ouds.core.utilities.OudsPreview
+import com.orange.ouds.theme.OudsVersion
+import kotlin.reflect.full.declaredMemberProperties
+
+@Composable
+fun AboutVersionsScreen() {
+    Screen {
+        LazyColumn {
+            item {
+                VersionsSectionTitle(titleRes = R.string.app_about_versions_tokens_label)
+            }
+            items(getVersions<OudsVersion.Tokens>()) { version ->
+                Version(version = version)
+            }
+            item {
+                VersionsSectionTitle(
+                    modifier = Modifier.padding(top = OudsTheme.spaces.fixed.small),
+                    titleRes = R.string.app_about_versions_components_label
+                )
+            }
+            items(getVersions<OudsVersion.Component>()) { version ->
+                Version(version = version)
+            }
+        }
+    }
+}
+
+@Composable
+private fun VersionsSectionTitle(@StringRes titleRes: Int, modifier: Modifier = Modifier) {
+    ListItem(
+        modifier = modifier.listItemHorizontalPadding(),
+        headlineContent = {
+            Text(
+                text = stringResource(id = titleRes),
+                style = OudsTheme.typography.heading.medium
+            )
+        }
+    )
+}
+
+@Composable
+private fun Version(version: Version) {
+    ListItem(
+        modifier = Modifier.listItemHorizontalPadding(),
+        headlineContent = {
+            Text(
+                text = version.name,
+                style = OudsTheme.typography.body.strong.large
+            )
+        },
+        trailingContent = {
+            Text(
+                text = version.value,
+                style = OudsTheme.typography.body.default.large
+            )
+        }
+    )
+}
+
+private data class Version(val name: String, val value: String)
+
+private inline fun <reified T : Any> getVersions(): List<Version> {
+    return T::class.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
+        Version(name, value)
+    }
+}
+
+@PreviewLightDark
+@Composable
+fun PreviewVersionsScreen() = OudsPreview {
+    AboutVersionsScreen()
+}

app/src/main/java/com/orange/ouds/app/ui/components/badge/BadgeDemoScreen.kt

@@ -40,6 +40,7 @@ import com.orange.ouds.core.component.OudsBadge
 import com.orange.ouds.core.theme.OudsTheme
 import com.orange.ouds.core.utilities.OudsPreview
 import com.orange.ouds.foundation.extensions.orElse
+import com.orange.ouds.theme.OudsVersion
 
 @Composable
 fun BadgeDemoScreen() {
@@ -48,7 +49,8 @@ fun BadgeDemoScreen() {
         description = stringResource(id = Component.Badge.descriptionRes),
         bottomSheetContent = { BadgeDemoBottomSheetContent(state = state) },
         codeSnippet = { badgeDemoCodeSnippet(state = state) },
-        demoContent = { BadgeDemoContent(state = state) }
+        demoContent = { BadgeDemoContent(state = state) },
+        version = OudsVersion.Component.Badge
     )
 }
 

app/src/main/java/com/orange/ouds/app/ui/components/button/ButtonDemoScreen.kt

@@ -35,6 +35,7 @@ import com.orange.ouds.app.ui.utilities.composable.DemoScreen
 import com.orange.ouds.core.component.OudsButton
 import com.orange.ouds.core.theme.OudsTheme
 import com.orange.ouds.core.utilities.OudsPreview
+import com.orange.ouds.theme.OudsVersion
 
 @Composable
 fun ButtonDemoScreen() {
@@ -44,7 +45,8 @@ fun ButtonDemoScreen() {
         bottomSheetContent = { ButtonDemoBottomSheetContent(state = state) },
         codeSnippet = { buttonDemoCodeSnippet(state = state) },
         demoContent = { ButtonDemoContent(state = state) },
-        demoContentOnColoredBox = state.onColoredBox
+        demoContentOnColoredBox = state.onColoredBox,
+        version = OudsVersion.Component.Button
     )
 }
 

app/src/main/java/com/orange/ouds/app/ui/components/checkbox/CheckboxDemoScreen.kt

@@ -28,6 +28,7 @@ import com.orange.ouds.app.ui.utilities.composable.DemoScreen
 import com.orange.ouds.core.component.OudsCheckbox
 import com.orange.ouds.core.component.OudsTriStateCheckbox
 import com.orange.ouds.core.utilities.OudsPreview
+import com.orange.ouds.theme.OudsVersion
 
 @Composable
 fun CheckboxDemoScreen(indeterminate: Boolean = false) {
@@ -41,7 +42,8 @@ fun CheckboxDemoScreen(indeterminate: Boolean = false) {
             } else {
                 CheckboxDemoContent(state = state)
             }
-        }
+        },
+        version = OudsVersion.Component.Checkbox
     )
 }
 

app/src/main/java/com/orange/ouds/app/ui/components/checkbox/CheckboxItemDemoScreen.kt

@@ -27,6 +27,7 @@ import com.orange.ouds.core.component.OudsCheckboxItem
 import com.orange.ouds.core.component.OudsControlItem
 import com.orange.ouds.core.component.OudsTriStateCheckboxItem
 import com.orange.ouds.core.utilities.OudsPreview
+import com.orange.ouds.theme.OudsVersion
 
 @Composable
 fun CheckboxItemDemoScreen(indeterminate: Boolean = false) {
@@ -41,7 +42,8 @@ fun CheckboxItemDemoScreen(indeterminate: Boolean = false) {
                 CheckboxItemDemoContent(state = state)
             }
         },
-        demoContentPaddingValues = PaddingValues()
+        demoContentPaddingValues = PaddingValues(),
+        version = OudsVersion.Component.Checkbox
     )
 }