Remove unnecessary configuration of Dokka Engine transitive dependenc…

…ies. DGP should only depend on Dokka Engine, and not prescriptively control what dependencies to declare. KT-71382
Kotlin · Sep 18, 2024 · d9dd54b · d9dd54b
1 parent 9fc4da1
commit d9dd54b
Show file tree

Hide file tree

Showing 9 changed files with 75 additions and 80 deletions.
diff --git a/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api b/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api
@@ -80,6 +80,7 @@ public abstract class org/jetbrains/dokka/gradle/DokkaExtension : java/io/Serial
 	public final fun ProcessIsolation (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$Process;
 	public static synthetic fun ProcessIsolation$default (Lorg/jetbrains/dokka/gradle/DokkaExtension;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lorg/jetbrains/dokka/gradle/workers/WorkerIsolation$Process;
 	public abstract fun getDokkaCacheDirectory ()Lorg/gradle/api/file/DirectoryProperty;
+	public abstract fun getDokkaEngineVersion ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDokkaGeneratorIsolation ()Lorg/gradle/api/provider/Property;
 	public abstract fun getDokkaModuleDirectory ()Lorg/gradle/api/file/DirectoryProperty;
 	public abstract fun getDokkaPublicationDirectory ()Lorg/gradle/api/file/DirectoryProperty;
@@ -90,19 +91,6 @@ public abstract class org/jetbrains/dokka/gradle/DokkaExtension : java/io/Serial
 	public abstract fun getModuleVersion ()Lorg/gradle/api/provider/Property;
 	public final fun getPluginsConfiguration ()Lorg/gradle/api/ExtensiblePolymorphicDomainObjectContainer;
 	public abstract fun getSourceSetScopeDefault ()Lorg/gradle/api/provider/Property;
-	public final fun getVersions ()Lorg/jetbrains/dokka/gradle/DokkaExtension$Versions;
-}
-
-public abstract interface class org/jetbrains/dokka/gradle/DokkaExtension$Versions : org/gradle/api/plugins/ExtensionAware {
-	public static final field Companion Lorg/jetbrains/dokka/gradle/DokkaExtension$Versions$Companion;
-	public abstract fun getFreemarker ()Lorg/gradle/api/provider/Property;
-	public abstract fun getJetbrainsDokka ()Lorg/gradle/api/provider/Property;
-	public abstract fun getJetbrainsMarkdown ()Lorg/gradle/api/provider/Property;
-	public abstract fun getKotlinxCoroutines ()Lorg/gradle/api/provider/Property;
-	public abstract fun getKotlinxHtml ()Lorg/gradle/api/provider/Property;
-}
-
-public final class org/jetbrains/dokka/gradle/DokkaExtension$Versions$Companion {
 }
 
 public abstract interface class org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout {

diff --git a/dokka-runners/dokka-gradle-plugin/build.gradle.kts b/dokka-runners/dokka-gradle-plugin/build.gradle.kts
@@ -213,10 +213,6 @@ apiValidation {
 val generateDokkaGradlePluginConstants by tasks.registering(GenerateDokkaGradlePluginConstants::class) {
     val dokkaPluginConstants = objects.mapProperty<String, String>().apply {
         put("DOKKA_VERSION", project.version.toString())
-        put("DOKKA_DEPENDENCY_VERSION_KOTLINX_HTML", libs.versions.kotlinx.html)
-        put("DOKKA_DEPENDENCY_VERSION_KOTLINX_COROUTINES", libs.versions.kotlinx.coroutines)
-        put("DOKKA_DEPENDENCY_VERSION_FREEMARKER", libs.versions.freemarker)
-        put("DOKKA_DEPENDENCY_VERSION_JETBRAINS_MARKDOWN", libs.versions.jetbrains.markdown)
     }
 
     properties.set(dokkaPluginConstants)

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaBasePlugin.kt
@@ -104,14 +104,8 @@ constructor(
             dokkaModuleDirectory.convention(layout.buildDirectory.dir("dokka-module"))
 //            @Suppress("DEPRECATION")
 //            dokkaConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config"))
-        }
 
-        dokkaExtension.versions {
-            jetbrainsDokka.convention(DokkaConstants.DOKKA_VERSION)
-            jetbrainsMarkdown.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_JETBRAINS_MARKDOWN)
-            freemarker.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_FREEMARKER)
-            kotlinxHtml.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_KOTLINX_HTML)
-            kotlinxCoroutines.convention(DokkaConstants.DOKKA_DEPENDENCY_VERSION_KOTLINX_COROUTINES)
+            dokkaEngineVersion.convention(DokkaConstants.DOKKA_VERSION)
         }
 
         dokkaExtension.dokkaGeneratorIsolation.convention(
@@ -214,7 +208,6 @@ constructor(
                 suppress.convention(false)
                 skipDeprecated.convention(false)
                 reportUndocumented.convention(false)
-                documentedVisibilities.convention(listOf(VisibilityModifier.Public))
             }
 
             externalDocumentationLinks {

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/DokkaExtension.kt
@@ -122,24 +122,12 @@ constructor(
         extensions.adding("pluginsConfiguration", objects.dokkaPluginParametersContainer())
 
     /**
-     * Versions of dependencies that Dokka Gradle Plugin will use to run Dokka Generator.
+     * The default version of Dokka dependencies that are used at runtime during generation.
      *
-     * These versions can be set to change the versions of dependencies that Dokka Gradle Plugin uses by default,
-     * or can be read to align versions.
+     * This value defaults to the current Dokka Gradle Plugin version, but can be overridden
+     * if you want to use a newer or older version of Dokka at runtime.
      */
-    val versions: Versions = extensions.adding("versions", objects.newInstance())
-
-    interface Versions : ExtensionAware {
-
-        /** Default version used for Dokka dependencies */
-        val jetbrainsDokka: Property<String>
-        val jetbrainsMarkdown: Property<String>
-        val freemarker: Property<String>
-        val kotlinxHtml: Property<String>
-        val kotlinxCoroutines: Property<String>
-
-        companion object
-    }
+    abstract val dokkaEngineVersion: Property<String>
 
     /**
      * Dokka Gradle Plugin runs Dokka Generator in a separate

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaFormatPlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaFormatPlugin.kt
@@ -15,7 +15,6 @@ import org.gradle.api.file.FileSystemOperations
 import org.gradle.api.file.ProjectLayout
 import org.gradle.api.logging.Logging
 import org.gradle.api.model.ObjectFactory
-import org.gradle.api.provider.Property
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
 import org.gradle.kotlin.dsl.*
@@ -134,8 +133,9 @@ abstract class DokkaFormatPlugin(
                     // https://github.com/gradle/gradle/issues/27435)
                     dependenciesContainer.resolutionStrategy.eachDependency {
                         if (requested.group == "org.jetbrains.dokka" && requested.version.isNullOrBlank()) {
-                            logger.info("adding version of dokka dependency '$requested'")
-                            useVersion(dokkaExtension.versions.jetbrainsDokka.get())
+                            val dokkaVersion = dokkaExtension.dokkaEngineVersion.get()
+                            logger.info("[${context.project.path}] adding Dokka version $dokkaVersion to dependency '$requested'")
+                            useVersion(dokkaVersion)
                         }
                     }
                 }
@@ -164,7 +164,7 @@ abstract class DokkaFormatPlugin(
 
         /** Create a [Dependency] for a Dokka module */
         fun DependencyHandler.dokka(module: String): Provider<Dependency> =
-            dokkaExtension.versions.jetbrainsDokka.map { version -> create("org.jetbrains.dokka:$module:$version") }
+            dokkaExtension.dokkaEngineVersion.map { version -> create("org.jetbrains.dokka:$module:$version") }
 
         private fun AttributeContainer.dokkaPluginsClasspath() {
             attribute(DokkaFormatAttribute, formatDependencies.formatAttributes.format.name)
@@ -211,27 +211,17 @@ abstract class DokkaFormatPlugin(
 
     private fun DokkaFormatPluginContext.addDefaultDokkaDependencies() {
         project.dependencies {
-            /** lazily create a [Dependency] with the provided [version] */
-            infix fun String.version(version: Property<String>): Provider<Dependency> =
-                version.map { v -> create("$this:$v") }
-
-            with(dokkaExtension.versions) {
-                dokkaPlugin(dokka("templating-plugin"))
-                dokkaPlugin(dokka("dokka-base"))
-
-                dokkaGenerator(
-                    if (project.pluginFeaturesService.enableK2Analysis) {
-                        dokka("analysis-kotlin-symbols") // K2 analysis
-                    } else {
-                        dokka("analysis-kotlin-descriptors") // K1 analysis
-                    }
-                )
-                dokkaGenerator(dokka("dokka-core"))
-                dokkaGenerator("org.freemarker:freemarker" version freemarker)
-                dokkaGenerator("org.jetbrains:markdown" version jetbrainsMarkdown)
-                dokkaGenerator("org.jetbrains.kotlinx:kotlinx-coroutines-core" version kotlinxCoroutines)
-                dokkaGenerator("org.jetbrains.kotlinx:kotlinx-html" version kotlinxHtml)
-            }
+            dokkaPlugin(dokka("templating-plugin"))
+            dokkaPlugin(dokka("dokka-base"))
+
+            dokkaGenerator(
+                if (project.pluginFeaturesService.enableK2Analysis) {
+                    dokka("analysis-kotlin-symbols") // K2 analysis
+                } else {
+                    dokka("analysis-kotlin-descriptors") // K1 analysis
+                }
+            )
+            dokkaGenerator(dokka("dokka-core"))
         }
     }
 

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaHtmlPlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaHtmlPlugin.kt
@@ -104,10 +104,9 @@ constructor(
 
         formatDependencies.dokkaPublicationPluginClasspathApiOnly
             .dependencies
-            .addLater(dokkaExtension.versions.jetbrainsDokka.map { v ->
+            .addLater(dokkaExtension.dokkaEngineVersion.map { v ->
                 project.dependencies.create("org.jetbrains.dokka:all-modules-page-plugin:$v")
             })
-
     }
 
     /**

diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/gradleExtensionAccessors.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/gradleExtensionAccessors.kt
diff --git a/...ns/DokkaVersioningPluginParametersTest.kt → ...ns/DokkaVersioningPluginParametersTest.kt b/...ns/DokkaVersioningPluginParametersTest.kt → ...ns/DokkaVersioningPluginParametersTest.kt
diff --git a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/formats/DokkaFormatPluginTest.kt b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/formats/DokkaFormatPluginTest.kt
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package org.jetbrains.dokka.gradle.formats
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.collections.shouldContainExactlyInAnyOrder
+import org.gradle.api.artifacts.result.UnresolvedDependencyResult
+import org.gradle.kotlin.dsl.apply
+import org.gradle.kotlin.dsl.configure
+import org.gradle.testfixtures.ProjectBuilder
+import org.jetbrains.dokka.gradle.DokkaExtension
+import org.jetbrains.dokka.gradle.DokkaPlugin
+import org.jetbrains.dokka.gradle.utils.enableV2Plugin
+
+class DokkaFormatPluginTest : FunSpec({
+
+    context("version alignment") {
+
+        context("When project has a org.jetbrains.dokka dependency without a version") {
+            val project = ProjectBuilder.builder().build()
+                .enableV2Plugin()
+            project.pluginManager.apply(type = DokkaPlugin::class)
+
+            project.extensions.configure<DokkaExtension> {
+                dokkaEngineVersion.convention("1.2.3")
+            }
+
+            project.dependencies.add("dokkaPlugin", "org.jetbrains.dokka:xyz")
+
+            test("expect Dokka version defaults to DokkaExtension.versions.dokkaEngine") {
+                project.configurations
+                    .getByName("dokkaHtmlPluginIntransitiveResolver~internal")
+                    .incoming
+                    .resolutionResult
+                    .root
+                    .dependencies
+                    .map {
+                        // 1.2.3 is not a valid Dokka version, so expect 'unresolved' dependencies,
+                        // but that's fine, we only want to check that attempt contains the custom version.
+                        it as UnresolvedDependencyResult
+                        it.attempted.displayName
+                    }
+                    .shouldContainExactlyInAnyOrder(
+                        "org.jetbrains.dokka:xyz:1.2.3",
+                        // DGP adds these dependencies automatically
+                        "org.jetbrains.dokka:templating-plugin:1.2.3",
+                        "org.jetbrains.dokka:dokka-base:1.2.3",
+                    )
+            }
+        }
+    }
+})