Add Gradle tasks to check and update documentation

Author: florentmaitre

app/build.gradle.kts

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

build.gradle.kts

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

buildSrc/src/main/kotlin/com/orange/ouds/gradle/Component.kt

@@ -0,0 +1,56 @@
+/*
+ * 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.gradle
+
+import com.orange.ouds.theme.OudsVersion
+import org.gradle.api.Project
+
+enum class Component {
+    Badge,
+    Button,
+    Checkbox,
+    Chip,
+    Divider,
+    Link,
+    RadioButton,
+    Switch;
+
+    val version: String
+        get() = with(OudsVersion.Component) {
+            when (this@Component) {
+                Component.Badge -> Badge
+                Component.Button -> Button
+                Component.Checkbox -> Checkbox
+                Component.Chip -> Chip
+                Component.Divider -> Divider
+                Component.Link -> Link
+                Component.RadioButton -> RadioButton
+                Component.Switch -> Switch
+            }
+        }
+
+    fun getSourceFilePaths(project: Project): List<String> {
+        val filenames = when (this) {
+            Component.Badge -> listOf("OudsBadge")
+            Component.Button -> listOf("OudsButton")
+            Component.Checkbox -> listOf("OudsCheckbox", "OudsCheckboxItem")
+            Component.Chip -> listOf("OudsFilterChip", "OudsSuggestionChip")
+            Component.Divider -> listOf("OudsDivider")
+            Component.Link -> listOf("OudsLink")
+            Component.RadioButton -> listOf("OudsRadioButton", "OudsRadioButtonItem")
+            Component.Switch -> listOf("OudsSwitch", "OudsSwitchItem")
+        }
+
+        return filenames.map { "${project.rootProject.projectDir}/core/src/main/java/com/orange/ouds/core/component/$it.kt" }
+    }
+}

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

@@ -11,12 +11,15 @@
  */
 
 import com.github.mustachejava.DefaultMustacheFactory
+import com.orange.ouds.gradle.Component
 import com.orange.ouds.theme.OudsVersion
 import java.io.FileOutputStream
 import java.io.PrintWriter
 import kotlin.reflect.full.declaredMemberProperties
 
 tasks.register<DefaultTask>("prepareDocumentation") {
+    dependsOn(tasks["checkDocumentation"])
+
     doLast {
         val mustacheFactory = DefaultMustacheFactory()
 
@@ -54,3 +57,40 @@ tasks.register<DefaultTask>("prepareDocumentation") {
         }
     }
 }
+
+tasks.register<DefaultTask>("checkDocumentation") {
+    doLast {
+        val componentVersionRegex = "Design version: (.*)$".toRegex()
+        Component.values().forEach { component ->
+            component.getSourceFilePaths(project).forEach { sourceFilePath ->
+                val versionByLineIndex = File(sourceFilePath).readLines()
+                    .mapIndexedNotNull { index, line ->
+                        componentVersionRegex.find(line)
+                            ?.groupValues
+                            ?.getOrNull(1)
+                            ?.let { version ->
+                                index to version
+                            }
+                    }
+                versionByLineIndex.forEach { (lineIndex, version) ->
+                    if (version != component.version) {
+                        throw GradleException("Component version at line ${lineIndex + 1} in $sourceFilePath is not up to date. Please launch updateDocumentation Gradle task.")
+                    }
+                }
+            }
+        }
+    }
+}
+
+tasks.register<DefaultTask>("updateDocumentation") {
+    doLast {
+        val componentVersionRegex = "(Design version: ).*".toRegex()
+        Component.values().forEach { component ->
+            component.getSourceFilePaths(project).forEach { sourceFilePath ->
+                File(sourceFilePath).replace(componentVersionRegex) { matchResult ->
+                    "${matchResult.groupValues[1]}${component.version}"
+                }
+            }
+        }
+    }
+}

core/src/main/java/com/orange/ouds/core/component/OudsBadge.kt

@@ -56,7 +56,7 @@ import com.orange.ouds.core.utilities.PreviewEnumEntries
 import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider
 
 
-// TODO: Add documentation URL once it is available
+// TODO: Update documentation URL once it is available
 /**
  * The badge is a small UI element used to highlight status, notifications, or categorization within an interface.
  * It is often displayed as a label or indicator with a distinct background color and text.
@@ -71,6 +71,10 @@ import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider
  * See [BadgedBox] for a top level layout that will properly place the badge relative to content
  * such as text or an icon.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com)
+ *
+ * > Design version: 1.1.0
+ *
  * @param modifier The [Modifier] to be applied to this badge.
  * @param status The status of this badge. The background color of the badge is based on this status.
  * @param size The size of this badge.
@@ -92,7 +96,7 @@ fun OudsBadge(
     )
 }
 
-// TODO: Add documentation URL once it is available
+// TODO: Update documentation URL once it is available
 /**
  * The badge is a small UI element used to highlight status, notifications, or categorization within an interface.
  * It is often displayed as a label or indicator with a distinct background color and text.
@@ -105,6 +109,10 @@ fun OudsBadge(
  * See [BadgedBox] for a top level layout that will properly place the badge relative to content
  * such as text or an icon.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com)
+ *
+ * > Design version: 1.1.0
+ *
  * @param count The number displayed in the badge. Minimum and maximum values are 0 and 99 respectively.
  *   Values greater than 99 are displayed as "+99".
  * @param modifier The [Modifier] to be applied to this badge.
@@ -131,7 +139,7 @@ fun OudsBadge(
     )
 }
 
-// TODO: Add documentation URL once it is available
+// TODO: Update documentation URL once it is available
 /**
  * The badge is a small UI element used to highlight status, notifications, or categorization within an interface.
  * It is often displayed as a label or indicator with a distinct background color and text.
@@ -144,6 +152,10 @@ fun OudsBadge(
  * See [BadgedBox] for a top level layout that will properly place the badge relative to content
  * such as text or an icon.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com)
+ *
+ * > Design version: 1.1.0
+ *
  * @param icon The icon displayed in the badge.
  * @param modifier The [Modifier] to be applied to this badge.
  * @param status The status of this badge. The background color of the badge and the icon color are based on this status.

core/src/main/java/com/orange/ouds/core/component/OudsButton.kt

@@ -72,11 +72,10 @@ import com.orange.ouds.core.utilities.getPreviewEnumEntry
 import com.orange.ouds.foundation.extensions.ifNotNull
 import com.orange.ouds.foundation.extensions.orElse
 import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider
+import com.orange.ouds.theme.tokens.components.OudsButtonMonoTokens
 import kotlinx.parcelize.Parcelize
 
 /**
- * <a href="https://unified-design-system.orange.com/472794e18/p/48a788-button" class="external" target="_blank">**OUDS Button design guidelines**</a>
- *
  * Buttons are interactive elements designed to trigger specific actions or events when tapped by a user.
  *
  * This version of the button uses the *text only* layout which is the most used layout.
@@ -85,6 +84,10 @@ import kotlinx.parcelize.Parcelize
  * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed.
  * The tokens associated with these specific colors can be customized by overriding [OudsButtonMonoTokens].
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/48a788-button)
+ *
+ * > Design version: 2.1.0
+ *
  * @param label Label displayed in the button which describes the button action. Use action verbs or phrases to tell the user what will happen next.
  * @param onClick Callback invoked when the button is clicked.
  * @param modifier [Modifier] applied to the button.
@@ -125,8 +128,6 @@ fun OudsButton(
 }
 
 /**
- * <a href="https://unified-design-system.orange.com/472794e18/p/48a788-button" class="external" target="_blank">**OUDS Button design guidelines**</a>
- *
  * Buttons are interactive elements designed to trigger specific actions or events when tapped by a user.
  *
  * This version of the button uses the *icon only* layout which is typically used in business or back-office interfaces, it is rarely used alone (usually part of a group of elements).
@@ -135,6 +136,10 @@ fun OudsButton(
  * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed.
  * The tokens associated with these specific colors can be customized by overriding [OudsButtonMonoTokens].
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/48a788-button)
+ *
+ * > Design version: 2.1.0
+ *
  * @param icon Icon displayed in the button. Use an icon to add additional affordance where the icon has a clear and well-established meaning.
  * @param onClick Callback invoked when the button is clicked.
  * @param modifier [Modifier] applied to the button.
@@ -175,8 +180,6 @@ fun OudsButton(
 }
 
 /**
- * <a href="https://unified-design-system.orange.com/472794e18/p/48a788-button" class="external" target="_blank">**OUDS Button design guidelines**</a>
- *
  * Buttons are interactive elements designed to trigger specific actions or events when tapped by a user.
  *
  * This version of the button uses the *text + icon* layout which should remain specific to some clearly identified contexts (e.g. the use of an icon with a
@@ -186,6 +189,10 @@ fun OudsButton(
  * Note that in the case it is placed in an [OudsColoredBox], its monochrome variant is automatically displayed.
  * The tokens associated with these specific colors can be customized by overriding [OudsButtonMonoTokens].
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/48a788-button)
+ *
+ * > Design version: 2.1.0
+ *
  * @param icon Icon displayed in the button. Use an icon to add additional affordance where the icon has a clear and well-established meaning.
  * @param label Label displayed in the button which describes the button action. Use action verbs or phrases to tell the user what will happen next.
  * @param onClick Callback invoked when the button is clicked.

core/src/main/java/com/orange/ouds/core/component/OudsCheckbox.kt

@@ -50,13 +50,15 @@ import com.orange.ouds.core.utilities.getPreviewEnumEntry
 import com.orange.ouds.foundation.utilities.BasicPreviewParameterProvider
 
 /**
- * <a href="https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox" class="external" target="_blank">**OUDS Checkbox design guidelines**</a>
- *
  * Checkboxes are input controls that allow users to select one or more options from a number of choices.
  *
  * The **standalone checkbox variant** is used when the checkbox input is nested within another component and an alternative label is provided. For example,
  * a checkbox can be used in a data table where its purpose is clear from its position or its connection to other items in the same row or column.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox)
+ *
+ * > Design version: 2.1.0
+ *
  * @see [OudsTriStateCheckbox] If you require support for an indeterminate state.
  * @see [OudsCheckboxItem] If you want to use a checkbox with an associated label and other optional elements.
  *
@@ -93,9 +95,6 @@ fun OudsCheckbox(
 }
 
 /**
- *
- * <a href="https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox" class="external" target="_blank">**OUDS Checkbox design guidelines**</a>
- *
  * Checkboxes are input controls that allow users to select one or more options from a number of choices.
  *
  * This checkbox supports the indeterminate state: Checkboxes can have a parent-child relationship with other checkboxes. When the parent checkbox is checked,
@@ -105,6 +104,10 @@ fun OudsCheckbox(
  * The **indeterminate standalone checkbox variant** allows to manage a checkbox with an indeterminate state that can be used when the checkbox input is nested
  * within another component and an alternative label is provided.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox)
+ *
+ * > Design version: 2.1.0
+ *
  * @see [OudsCheckbox] If you need a simple component that represents [Boolean] state.
  * @see [OudsTriStateCheckboxItem] If you want to use an indeterminate checkbox with an associated label and other optional elements.
  *

core/src/main/java/com/orange/ouds/core/component/OudsCheckboxItem.kt

@@ -35,8 +35,6 @@ import com.orange.ouds.core.utilities.OudsPreview
 import com.orange.ouds.core.utilities.PreviewEnumEntries
 
 /**
- * <a href="https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox" class="external" target="_blank">**OUDS Checkbox design guidelines**</a>
- *
  * Checkboxes are input controls that allow users to select one or more options from a number of choices.
  *
  * The **checkbox item variant** can function as a simple input with a label, or it can be combined with optional elements such as helper text, a divider, or an icon,
@@ -47,6 +45,10 @@ import com.orange.ouds.core.utilities.PreviewEnumEntries
  * In most cases, OUDS checkbox items span the entire width of the screen. Thus an horizontal padding of `OudsTheme.grids.margin` is applied to the content.
  * This behaviour can be disabled by calling [com.orange.ouds.core.utilities.edgeToEdgePadding] modifier with `enabled` parameter set to `false`.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox)
+ *
+ * > Design version: 2.1.0
+ *
  * @see [OudsTriStateCheckboxItem] If you need an indeterminate state for the item's checkbox.
  * @see [OudsCheckbox] If you want to use a standalone checkbox without any other element.
  *
@@ -103,8 +105,6 @@ fun OudsCheckboxItem(
 }
 
 /**
- * <a href="https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox" class="external" target="_blank">**OUDS Checkbox design guidelines**</a>
- *
  * Checkboxes are input controls that allow users to select one or more options from a number of choices.
  *
  * This checkbox item supports the indeterminate state: Checkboxes can have a parent-child relationship with other checkboxes. When the parent checkbox is
@@ -120,6 +120,10 @@ fun OudsCheckboxItem(
  * In most cases, OUDS checkbox items span the entire width of the screen. Thus an horizontal padding of `OudsTheme.grids.margin` is applied to the content.
  * This behaviour can be disabled by calling [com.orange.ouds.core.utilities.edgeToEdgePadding] modifier with `enabled` parameter set to `false`.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/23f1c1-checkbox)
+ *
+ * > Design version: 2.1.0
+ *
  * @see [OudsCheckboxItem] If you need a simple item's checkbox that represents [Boolean] state.
  * @see [OudsTriStateCheckbox] If you only need an indeterminate standalone parent checkbox without any other element.
  *

core/src/main/java/com/orange/ouds/core/component/OudsDivider.kt

@@ -28,8 +28,6 @@ import com.orange.ouds.core.theme.value
 import com.orange.ouds.core.utilities.OudsPreview
 import com.orange.ouds.foundation.utilities.EnumPreviewParameterProvider
 
-//TODO Add DSM link when available
-// <a href="https://unified-design-system.orange.com/" class="external" target="_blank">**OUDS Divider design guidelines**</a>
 /**
  * Dividers are used to visually structure an interface by clearly separating content sections. It helps to improve readability and content organization
  * without introducing a strong hierarchy like a heading or a container would.
@@ -39,6 +37,10 @@ import com.orange.ouds.foundation.utilities.EnumPreviewParameterProvider
  * The color of the divider can be specified using the [OudsDivider.Color] enum, and the thickness is defined by the current theme's divider border width.
  * Note that a divider border width token set to 0 dp will produce a single pixel divider regardless of screen density.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/629e1b-divider)
+ *
+ * > Design version: 1.0.0
+ *
  * @param modifier [Modifier] applied to the divider.
  * @param color The color of the divider, chosen from the [OudsDivider.Color] enum. Default value set to `OudsDivider.Color.Default`.
  *
@@ -52,8 +54,6 @@ fun OudsHorizontalDivider(
     HorizontalDivider(modifier = modifier, color = color.value, thickness = OudsTheme.componentsTokens.divider.borderWidth.value)
 }
 
-//TODO Add DSM link when available
-// <a href="https://unified-design-system.orange.com/" class="external" target="_blank">**OUDS Divider design guidelines**</a>
 /**
  * Dividers are used to visually structure an interface by clearly separating content sections. It helps to improve readability and content organization
  * without introducing a strong hierarchy like a heading or a container would.
@@ -63,6 +63,10 @@ fun OudsHorizontalDivider(
  * The color of the divider can be specified using the [OudsDivider.Color] enum, and the thickness is defined by the current theme's divider border width.
  * Note that a divider border width token set to 0 dp will produce a single pixel divider regardless of screen density.
  *
+ * > Design guidelines: [unified-design-system.orange.com](https://unified-design-system.orange.com/472794e18/p/629e1b-divider)
+ *
+ * > Design version: 1.0.0
+ *
  * @param modifier [Modifier] applied to the divider.
  * @param color The color of the divider, chosen from the [OudsDivider.Color] enum. Default value set to `OudsDivider.Color.Default`.
  *