Update to Dokka 2.0.0-Beta (#767)

build-logic/plugins/build.gradle.kts

@@ -26,6 +26,7 @@ tasks.withType<KotlinCompile>().configureEach {
 dependencies {
     compileOnly(libs.android.gradle.api)
     compileOnly(libs.detekt.gradle.plugin)
+    compileOnly(libs.dokka.gradle.plugin)
     compileOnly(libs.kotlinx.kover.gradle)
     compileOnly(libs.kotlin.gradle.plugin)
 

build-logic/plugins/src/main/java/ch/srgssr/pillarbox/gradle/PillarboxAndroidLibraryPublishingPlugin.kt

@@ -13,7 +13,11 @@ import org.gradle.api.publish.maven.MavenPublication
 import org.gradle.jvm.tasks.Jar
 import org.gradle.kotlin.dsl.configure
 import org.gradle.kotlin.dsl.get
+import org.gradle.kotlin.dsl.getByName
 import org.gradle.kotlin.dsl.register
+import org.jetbrains.dokka.gradle.DokkaExtension
+import org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters
+import java.net.URI
 
 /**
  * Custom Gradle plugin to configure publication in an Android library module for Pillarbox.
@@ -81,5 +85,27 @@ class PillarboxAndroidLibraryPublishingPlugin : Plugin<Project> {
                 }
             }
         }
+
+        extensions.configure<DokkaExtension> {
+            dokkaSourceSets.getByName("main") {
+                includes.from("Module.md")
+
+                // This is currently broken in Dokka for Android modules. See: https://github.com/Kotlin/dokka/issues/2876
+                sourceLink {
+                    val version = VersionConfig().versionName(default = name)
+
+                    localDirectory.set(projectDir.resolve("src"))
+                    remoteUrl.set(URI("https://github.com/SRGSSR/pillarbox-android/tree/$version/${target.name}/src"))
+                }
+            }
+
+            // Follow https://github.com/Kotlin/dokka/issues/3883 to see if it's necessary to duplicate this config
+            pluginsConfiguration.getByName<DokkaHtmlPluginParameters>("html") {
+                customStyleSheets.from(rootProject.projectDir.resolve("dokka/styles/pillarbox.css"))
+                footerMessage.set("© SRG SSR")
+                homepageLink.set("https://srgssr.github.io/pillarbox-android")
+                templatesDir.set(rootProject.projectDir.resolve("dokka/templates"))
+            }
+        }
     }
 }

build-logic/plugins/src/main/java/ch/srgssr/pillarbox/gradle/internal/VersionConfig.kt

@@ -19,10 +19,12 @@ internal class VersionConfig(
     /**
      * Version name
      *
+     * @param default The default value to use if no version name is available.
+     *
      * @return "Local" if [envVersionName] no set.
      */
-    internal fun versionName(): String {
-        return envVersionName ?: "Local"
+    internal fun versionName(default: String = "Local"): String {
+        return envVersionName ?: default
     }
 
     /**

build-logic/plugins/src/test/java/ch/srgssr/pillarbox/gradle/internal/VersionConfigTest.kt

@@ -29,6 +29,12 @@ class VersionConfigTest(
         assertEquals(versionName, versionConfig.versionName())
     }
 
+    @Test
+    fun `version name with default`() {
+        assertEquals("dev", VersionConfig().versionName(default = "dev"))
+        assertEquals("1.2.3", VersionConfig(envVersionName = "1.2.3").versionName(default = "dev"))
+    }
+
     @Test
     fun `version code`() {
         assertEquals(versionCode, versionConfig.versionCode())

build.gradle.kts

@@ -2,6 +2,7 @@
  * Copyright (c) SRG SSR. All rights reserved.
  * License information is available from the LICENSE file.
  */
+import org.jetbrains.dokka.gradle.tasks.DokkaGenerateTask
 
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
@@ -12,18 +13,44 @@ plugins {
     alias(libs.plugins.kotlin.parcelize) apply false
     alias(libs.plugins.detekt)
     alias(libs.plugins.dependency.analysis.gradle.plugin)
-    alias(libs.plugins.dokka) apply false
+    alias(libs.plugins.dokka)
     alias(libs.plugins.kotlinx.kover)
     alias(libs.plugins.pillarbox.detekt)
 }
 
+tasks.withType<DokkaGenerateTask> {
+    generator.includes.from("dokka/Pillarbox.md")
+}
+
+dokka {
+    moduleVersion = providers.environmentVariable("VERSION_NAME").orElse("dev")
+
+    pluginsConfiguration.html {
+        // See the overridable images here:
+        // https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-base/src/main/resources/dokka/images
+        customAssets.from("dokka/images/logo-icon.svg") // TODO Use Pillarbox logo
+        customStyleSheets.from("dokka/styles/pillarbox.css")
+        footerMessage.set("© SRG SSR")
+        homepageLink.set("https://srgssr.github.io/pillarbox-android")
+        templatesDir.set(file("dokka/templates"))
+    }
+}
+
+dependencies {
+    dokka(project(":pillarbox-analytics"))
+    dokka(project(":pillarbox-cast"))
+    dokka(project(":pillarbox-core-business"))
+    dokka(project(":pillarbox-player"))
+    dokka(project(":pillarbox-ui"))
+}
+
 // Configure the `wrapper` task, so it can easily be updated by simply running `./gradlew wrapper`.
 tasks.wrapper {
     distributionType = Wrapper.DistributionType.ALL
     gradleVersion = "latest"
 }
 
-val clean by tasks.registering(Delete::class) {
+val clean by tasks.getting(Delete::class) {
     delete(rootProject.layout.buildDirectory)
 }
 

dokka/Pillarbox.md

@@ -0,0 +1,14 @@
+<!-- Workaround https://github.com/Kotlin/dokka/issues/3886 -->
+<h1 class="cover"><span><span>Pillarbox Player for Android</span></span></h1>
+
+Pillarbox is the modern SRG SSR multimedia player ecosystem, built on top of [AndroidX Media3](https://developer.android.com/media/media3).
+Pillarbox has been designed with robustness, flexibility, and efficiency in mind, with many customization options available.
+
+It is split in multiple modules, whose documentation is available from the side menu.
+
+## Additional resources:
+
+- [GitHub repository](https://github.com/SRGSSR/pillarbox-android)
+- [Pillarbox releases](https://github.com/SRGSSR/pillarbox-android/releases)
+- [Pillarbox for Apple](https://swiftpackageindex.com/SRGSSR/pillarbox-apple)
+- [Pillarbox for the Web](https://srgssr.github.io/pillarbox-web/api)

dokka/styles/pillarbox.css

@@ -0,0 +1,3 @@
+#filter-section, .platform-tags {
+    display: none;
+}

dokka/templates/includes/page_metadata.ftl

@@ -0,0 +1,12 @@
+<#-- This changes the page title to "Pillarbox" on the homepage -->
+<#-- https://github.com/Kotlin/dokka/blob/master/dokka-subprojects/plugin-base/src/main/resources/dokka/templates/includes/page_metadata.ftl -->
+<#macro display>
+    <#if pageName == "All modules">
+        <title>Pillarbox</title>
+    <#else>
+        <title>${pageName}</title>
+    </#if>
+    <@template_cmd name="pathToRoot">
+    <link href="${pathToRoot}images/logo-icon.svg" rel="icon" type="image/svg">
+    </@template_cmd>
+</#macro>

gradle.properties

@@ -1,3 +1,8 @@
+#
+# Copyright (c) SRG SSR. All rights reserved.
+# License information is available from the LICENSE file.
+#
+
 # Project-wide Gradle settings.
 # IDE (e.g. Android Studio) users:
 # Gradle settings configured through the IDE *will override*
@@ -23,11 +28,14 @@ android.useAndroidX=true
 kotlin.code.style=official
 
 org.gradle.caching=true
-# Disable configuration cache until Dokka supports it: https://github.com/Kotlin/dokka/issues/1217
-org.gradle.configuration-cache=false
+org.gradle.configuration-cache=true
 
 # Print dependency analysis report to the console
 dependency.analysis.print.build.health=true
 
 # Let Detekt use Gradle's Worker API (https://detekt.dev/docs/gettingstarted/gradle/#options-for-detekt-gradle-properties)
 detekt.use.worker.api=true
+
+# Use Dokka 2 Gradle Plugin: https://kotlinlang.org/docs/dokka-migration.html#migrate-your-project
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true

gradle/libs.versions.toml

@@ -20,7 +20,7 @@ coil = "2.7.0"
 comscore = "6.11.1"
 dependency-analysis-gradle-plugin = "2.3.0"
 detekt = "1.23.7"
-dokka = "1.9.20"
+dokka = "2.0.0-Beta"
 guava = "33.0.0-android"
 json = "20240303"
 junit = "4.13.2"
@@ -65,6 +65,7 @@ androidx-test-runner = { module = "androidx.test:runner", version.ref = "android
 androidx-tv-material = { module = "androidx.tv:tv-material", version.ref = "androidx-tv-material" }
 coil = { group = "io.coil-kt", name = "coil-compose", version.ref = "coil" }
 coil-base = { module = "io.coil-kt:coil-compose-base", version.ref = "coil" }
+dokka-gradle-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" }
 json = { module = "org.json:json", version.ref = "json" }
 kotlin-gradle-plugin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
 kotlin-parcelize-runtime = { module = "org.jetbrains.kotlin:kotlin-parcelize-runtime", version.ref = "kotlin" }

pillarbox-analytics/Module.md

@@ -0,0 +1,12 @@
+# Module pillarbox-analytics
+
+Provides SRG SSR implementation for [CommandersAct](https://www.commandersact.com/) and [ComScore](https://comscore.com/) to send page view events and
+custom events.
+
+> ⚠️ Custom events are only supported with CommandersAct!
+
+To use this module, add the following dependency to your project's `build.gradle`/`build.gradle.kts` file:
+
+```kotlin
+implementation("ch.srgssr.pillarbox:pillarbox-analytics:<pillarbox_version>")
+```

pillarbox-cast/Module.md

@@ -0,0 +1,9 @@
+# Module pillarbox-cast
+
+Provides helpers to integrate Cast with Pillarbox.
+
+To use this module, add the following dependency to your project's `build.gradle`/`build.gradle.kts` file:
+
+```kotlin
+implementation("ch.srgssr.pillarbox:pillarbox-cast:<pillarbox_version>")
+```

pillarbox-core-business/Module.md

@@ -0,0 +1,19 @@
+# Module pillarbox-core-business
+
+Provides a [`MediaSource`](https://developer.android.com/reference/androidx/media3/exoplayer/source/MediaSource) for handling SRG SSR media URNs to
+Pillarbox. It basically converts an integration layer [`MediaComposition`](ch.srgssr.pillarbox.core.business.integrationlayer.data.MediaComposition)
+to a playable `MediaSource`.
+
+The supported contents are:
+
+- On demand video and audio.
+- Live streams, with and without DRM.
+- Token-protected content.
+- DRM protected content.
+- 360° content (see [`SphericalSurfaceShowcase`](https://github.com/SRGSSR/pillarbox-android/tree/main/pillarbox-demo/src/main/java/ch/srgssr/pillarbox/demo/ui/showcases/misc/SphericalSurfaceShowcase.kt)).
+
+To use this module, add the following dependency to your project's `build.gradle`/`build.gradle.kts` file:
+
+```kotlin
+implementation("ch.srgssr.pillarbox:pillarbox-core-business:<pillarbox_version>")
+```

pillarbox-player/Module.md

@@ -0,0 +1,10 @@
+# Module pillarbox-player
+
+Provides [`PillarboxPlayer`](ch.srgssr.pillarbox.player.PillarboxPlayer), the
+[`Exoplayer`](https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer) implementation of media playback on Android.
+
+To use this module, add the following dependency to your project's `build.gradle`/`build.gradle.kts` file:
+
+```kotlin
+implementation("ch.srgssr.pillarbox:pillarbox-player:<pillarbox_version>")
+```

pillarbox-ui/Module.md

@@ -0,0 +1,13 @@
+# Module pillarbox-ui
+
+Provides UI Compose components:
+
+- [`PlayerSurface`](ch.srgssr.pillarbox.ui.widget.player.PlayerSurface).
+- Compose wrapper for ExoPlayer views.
+- [`ProgressTracker`](ch.srgssr.pillarbox.ui.ProgressTrackerState) to connect the player to a progress bar or slider.
+
+To use this module, add the following dependency to your project's `build.gradle`/`build.gradle.kts` file:
+
+```kotlin
+implementation("ch.srgssr.pillarbox:pillarbox-ui:<pillarbox_version>")
+```