Merge pull request #126 from NordicPlayground/migration/agp2.6

Migration Nordic Gradle Plugins 2.6.1 and new documentation

Author: philips77

.github/workflows/deploy-to-nexus.yml

@@ -13,8 +13,8 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-java@v4
         with:
-          distribution: 'corretto'
-          java-version: '17'
+          distribution: 'jetbrains'
+          java-version: '21'
       - shell: bash
         env:
           # The following env variables are used by gradle/publish-module.gradle

README.md

@@ -1,73 +1,25 @@
 # Nordic Common Libraries for Android
-A libraries with Nordic's common code for Android apps.
-
-## Theme
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:theme:<version>'
-```
-
-### Content
-The library contains a few features which are necessary for theming Nordic Semiconductor apps:
-
-* Color palette adopted to the new Material You
-* Typography
-* Nordic theme for dark and light mode
-* Abstract `NordicActivity` class which contain implementations for Nordic's splash screen animation.
-* `WizardStepComponent` for wizard-based app flow.
-* `CircularIcon` an icon with circular shape.
-* Other common views available for different projects.
-
-## Permission
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:permission:<version>'
-```
-
-### Content
-Classes and views related to managing permissions, including Bluetooth and Internet permissions.
 
-## Navigation
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:navigation:<version>'
-```
-
-### Content
-Common navigation components for the app.
-
-## UI Scanner
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:uiscanner:<version>'
-```
+A libraries with Nordic's common code for Android apps.
 
-### Content
-Common Bluetooth LE scanner screen.
+## Documentation
 
-## UI Logger
+The latest documentation can be found [here](https://nordicplayground.github.io/KAndroid-Common-Libraries/html/index.html).
 
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:uilogger:<version>'
-```
+## Usage
 
-### Content
-Common classes related with logging to nRF Logger app.
+To use this library, add the following to your `build.gradle` file:
 
-## Analytics
-
-### Usage
-```groovy
-implementation 'no.nordicsemi.android.common:analytics:<version>'
+```gradle
+dependencies {
+    implementation 'no.nordicsemi.android.common:<module>:<version>'
+}
 ```
 
-### Content
-Common views and classes related with gathering analytics data.
-
+## Sample app
 
+Run the sample app to see and test most of the components from the library.
 
+1. Clone the repository.
+2. Open the project in Android Studio.
+3. Run the `app` module on a connected device or emulator.

analytics/Module.md

@@ -0,0 +1,29 @@
+# Module analytics
+
+Set of classes related to Firebase Analytics.
+
+## Configuration
+
+Use of this module requires the following plugins to be applied in the app:
+```kotlin
+if (gradle.startParameter.taskRequests.toString().contains("Release")) {
+    apply("com.google.gms.google-services")
+    apply("com.google.firebase.crashlytics")
+}
+```
+and the _google-services.json_ file to be present in the app module.
+
+Read [Firebase Setup](https://firebase.google.com/docs/android/setup) for more.
+
+> **Note:**
+> 
+> This package requires Hilt, as it's using Dependency Injection to provide the 
+> [NordicAnalytics][no.nordicsemi.android.common.analytics.NordicAnalytics] class.
+
+# Package no.nordicsemi.android.common.analytics
+
+Main API for Nordic analytics. Contains set to methods to log events.
+
+# Package no.nordicsemi.android.common.analytics.view
+
+Set of common views used for enabling analytics in Nordic apps.

analytics/build.gradle.kts

@@ -51,6 +51,12 @@ android {
     namespace = "no.nordicsemi.android.common.analytics"
 }
 
+dokka {
+    dokkaSourceSets.named("main") {
+        includes.from("Module.md")
+    }
+}
+
 dependencies {
     implementation(project(":core"))
     implementation(project(":ui"))

analytics/module-rules.pro

@@ -29,6 +29,8 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.analytics
 
 import android.content.Context
@@ -45,14 +47,31 @@ import javax.inject.Singleton
 
 private const val LOG_TAG = "ANALYTICS"
 
+/**
+ * This class is responsible for logging events to Firebase Analytics.
+ *
+ * Use Hilt injection to get an instance of this class.
+ */
 @Singleton
 class NordicAnalytics @Inject internal constructor(
     @ApplicationContext private val context: Context,
     private val repository: AnalyticsPermissionRepository,
 ) {
+    /**
+     * A flow that emits the current Analytics permission data.
+     *
+     * @see AnalyticsPermissionData
+     */
     val permissionData = repository.permissionData
+
     private val firebase by lazy { FirebaseAnalytics.getInstance(context) }
 
+    /**
+     * Logs an event to Firebase Analytics, if the user has granted permission.
+     *
+     * @param name The name of the event. Should be between 1 and 40 characters long.
+     * @param params Optional parameters to be sent with the event.
+     */
     fun logEvent(@Size(min = 1L, max = 40L) name: String, params: Bundle? = null) {
         runBlocking {
             repository.permissionData.firstOrNull()
@@ -64,6 +83,11 @@ class NordicAnalytics @Inject internal constructor(
         }
     }
 
+    /**
+     * Sets whether analytics collection is enabled or disabled.
+     *
+     * @param isEnabled True to enable analytics collection, false to disable it.
+     */
     suspend fun setAnalyticsEnabled(isEnabled: Boolean) {
         if (isEnabled) {
             repository.onPermissionGranted()

analytics/src/main/java/no/nordicsemi/android/common/analytics/NordicAnalytics.kt

@@ -29,6 +29,8 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.analytics.view
 
 import androidx.compose.foundation.layout.fillMaxHeight

analytics/src/main/java/no/nordicsemi/android/common/analytics/view/AnalyticsPermissionRequestDialog.kt

@@ -29,6 +29,8 @@
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+@file:Suppress("unused")
+
 package no.nordicsemi.android.common.analytics.view
 
 import androidx.compose.foundation.clickable

analytics/src/main/java/no/nordicsemi/android/common/analytics/view/AnalyticsPermissionSettingsSwitch.kt

@@ -32,7 +32,6 @@ plugins {
     alias(libs.plugins.android.library) apply false
     alias(libs.plugins.hilt) apply false
     alias(libs.plugins.kotlin.parcelize) apply false
-    alias(libs.plugins.kotlin.dokka) apply false
     alias(libs.plugins.compose.compiler) apply false
 
     // Nordic plugins are defined in https://github.com/NordicSemiconductor/Android-Gradle-Plugins
@@ -43,4 +42,18 @@ plugins {
     alias(libs.plugins.nordic.hilt) apply false
     alias(libs.plugins.nordic.nexus.android) apply false
     alias(libs.plugins.nordic.kotlin.android) apply false
+
+    // This plugin is used to generate Dokka documentation.
+    alias(libs.plugins.kotlin.dokka) apply false
+    // This applies Nordic look & feel to generated Dokka documentation.
+    // https://github.com/NordicSemiconductor/Android-Gradle-Plugins/blob/main/plugins/src/main/kotlin/NordicDokkaPlugin.kt
+    alias(libs.plugins.nordic.dokka) apply true
 }
+
+// Configure main Dokka page
+dokka {
+    moduleName.set("Nordic Common Libraries")
+    pluginsConfiguration.html {
+        homepageLink.set("https://github.com/NordicPlayground/Android-Common-Libraries")
+    }
+}

build.gradle.kts

@@ -0,0 +1,7 @@
+# Module core
+
+Common classes and interfaces used by other modules.
+
+# Package no.nordicsemi.android.common.core
+
+Common classes and interfaces used by other modules.