Merge Dokkatoo into Dokka Gradle Plugin (#3695)

Initial Dokkatoo import

- merge DGP-classic into dokka-gradle-plugin
- add flag to toggle between DPG-classic and Dokkatoo
- Update Dokkatoo code to be Java-8 compatible
- update dokkatoo package name
- stop using `org.jetbrains.dokka.gradle.utils.sourceLink_` - weird class-not-found compilation issue
- update TaskPathCollector workaround
- fix LogHtmlPublicationLinkTask - use Http instead of Https connection
- Specify language/api as Kotlin 1.4 for dokka-gradle-plugin (to be compatible with Gradle 7)
- update api dump
- update formatting, add copyright header
- remove duplicated 'Isolation' from WorkerIsolation subtypes, & fix test
- renaming 'Dokkatoo' to 'Dokka'...
- fix process isolation worker jvm args
- add 'min supported Gradle' warning
- lazily fetch DokkaGradlePluginMode from `project.extra.properties`
- fixing KotlinNativeDistributionAccessor...
- fix DGP group/version
- add copyright header
- Change BCV to official BCV
- fix `toLowerCase()` deprecation
- remove `dokka-gradle-plugin` from `libs.versions.toml` (it's no longer used)
- remove duplicated plugin website/vcsUrl, move tags into specific Dokka plugin
- exclude Gradle's embedded-dependencies from DGP
- remove extraneous leftover groups

build-logic/build.gradle.kts

@@ -13,7 +13,6 @@ kotlin {
 }
 
 dependencies {
-    implementation(libs.gradlePlugin.dokka)
     implementation(libs.gradlePlugin.kotlin)
     implementation(libs.gradlePlugin.shadow)
     implementation("org.gradle.kotlin:gradle-kotlin-dsl-plugins:$expectedKotlinDslPluginsVersion")

build-logic/src/main/kotlin/dokkabuild.gradle-plugin.gradle.kts

@@ -2,34 +2,35 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import dokkabuild.utils.excludeGradleEmbeddedDependencies
+import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
 
 plugins {
     id("org.gradle.kotlin.kotlin-dsl")
     id("dokkabuild.java")
-    kotlin("jvm")
     id("dokkabuild.publish-gradle-plugin")
 }
 
-// org.gradle.kotlin.kotlin-dsl sets languageVersion and apiVersion to 1.8 by default starting from Gradle 8.
-// As we need to be compatible with previous Gradle versions, we need to set it back to 1.4.
-// Note: we should do it directly on tasks and not via top-level `kotlin.compilerOptions`
-//       because `kotlin-dsl plugin` declares them on task level, and so top-level config is overridden
-tasks.withType<KotlinCompile>().configureEach {
+kotlin {
     compilerOptions {
-        languageVersion = dokkaBuild.kotlinLanguageLevel
-        apiVersion = dokkaBuild.kotlinLanguageLevel
+        // Must use Kotlin 1.4 to support Gradle 7
+        languageVersion = @Suppress("DEPRECATION") KotlinVersion.KOTLIN_1_4
+        apiVersion = @Suppress("DEPRECATION") KotlinVersion.KOTLIN_1_4
+    }
+}
 
-        freeCompilerArgs.addAll(
-            // need 1.4 support, otherwise there might be problems
-            // with Gradle 6.x (it's bundling Kotlin 1.4)
-            "-Xsuppress-version-warnings",
-            "-Xjsr305=strict",
-            "-Xskip-metadata-version-check",
-        )
+tasks.compileKotlin {
+    compilerOptions {
+        // `kotlin-dsl` plugin overrides the versions at the task level,
+        // which takes priority over the `kotlin` project extension.
+        // So, fix it by manually setting the LV per-task.
+        languageVersion.set(kotlin.compilerOptions.languageVersion)
+        apiVersion.set(kotlin.compilerOptions.apiVersion)
     }
 }
 
 tasks.validatePlugins {
     enableStricterValidation = true
 }
+
+excludeGradleEmbeddedDependencies(sourceSets.main)

build-logic/src/main/kotlin/dokkabuild.java.gradle.kts

@@ -23,7 +23,7 @@ tasks.withType<Test>().configureEach {
     maxParallelForks = if (System.getenv("GITHUB_ACTIONS") != null) {
         Runtime.getRuntime().availableProcessors()
     } else {
-        (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1
+        (Runtime.getRuntime().availableProcessors() / 2).coerceAtLeast(1)
     }
 
     javaLauncher = javaToolchains.launcherFor {

build-logic/src/main/kotlin/dokkabuild/tasks/GenerateDokkaGradlePluginConstants.kt

@@ -0,0 +1,68 @@
+package dokkabuild.tasks
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.provider.MapProperty
+import org.gradle.api.tasks.CacheableTask
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import javax.inject.Inject
+
+@CacheableTask
+abstract class GenerateDokkaGradlePluginConstants @Inject constructor(
+    private val fs: FileSystemOperations
+) : DefaultTask() {
+
+    @get:OutputDirectory
+    abstract val destinationDir: DirectoryProperty
+
+    @get:Input
+    abstract val properties: MapProperty<String, String>
+
+    init {
+        group = project.name
+    }
+
+    @TaskAction
+    fun action() {
+        val properties = properties.get()
+
+        // prepare temp dir
+        fs.delete { delete(temporaryDir) }
+
+        // generate file
+        val vals = properties.entries
+            .sortedBy { it.key }
+            .joinToString("\n") { (k, v) ->
+                """const val $k = "$v""""
+            }.prependIndent("  ")
+
+        temporaryDir.resolve("DokkaConstants.kt").apply {
+            parentFile.mkdirs()
+            writeText(
+                """
+                |/*
+                | * 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.internal
+                |
+                |@DokkaInternalApi
+                |object DokkaConstants {
+                |$vals
+                |}
+                |
+                """.trimMargin()
+            )
+        }
+
+        // sync file to output dir
+        fs.sync {
+            from(temporaryDir) {
+                into("org/jetbrains/dokka/gradle/internal/")
+            }
+            into(destinationDir)
+        }
+    }
+}

build-logic/src/main/kotlin/dokkabuild/utils/gradle.kt

@@ -4,11 +4,18 @@
 
 package dokkabuild.utils
 
+import org.gradle.api.Action
+import org.gradle.api.NamedDomainObjectProvider
+import org.gradle.api.Project
 import org.gradle.api.artifacts.Configuration
+import org.gradle.api.artifacts.ModuleDependency
 import org.gradle.api.attributes.*
 import org.gradle.api.attributes.java.TargetJvmEnvironment
+import org.gradle.api.component.AdhocComponentWithVariants
 import org.gradle.api.model.ObjectFactory
-import org.gradle.kotlin.dsl.named
+import org.gradle.api.tasks.SourceSet
+import org.gradle.jvm.toolchain.JavaLanguageVersion
+import org.gradle.kotlin.dsl.*
 
 
 /**
@@ -87,3 +94,64 @@ internal fun AttributeContainer.jvmJar(objects: ObjectFactory) {
     attribute(TargetJvmEnvironment.TARGET_JVM_ENVIRONMENT_ATTRIBUTE, objects.named(TargetJvmEnvironment.STANDARD_JVM))
     attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(LibraryElements.JAR))
 }
+
+/**
+ * Pretty-print the Java name.
+ *
+ * For Java 8 and below the version is prefixed with `1.`.
+ */
+fun JavaLanguageVersion.formattedName(): String =
+    if (asInt() <= 8) "1.${asInt()}" else asInt().toString()
+
+/**
+ * Disable publishing of test fixtures (which causes warnings when publishing).
+ *
+ * https://docs.gradle.org/current/userguide/java_testing.html#publishing_test_fixtures
+ */
+fun Project.skipTestFixturesPublications() {
+    val javaComponent = components["java"] as AdhocComponentWithVariants
+    javaComponent.withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() }
+    javaComponent.withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() }
+}
+
+/**
+ * Exclude embedded Gradle dependencies from the given [SourceSet] configurations.
+ *
+ * The excluded dependencies are embedded into Gradle, they so should be excluded to prevent
+ * classpath ordering issues.
+ */
+// After extensive manual testing, it appears that these exclusions have no effect in dokka-gradle-plugin.
+//
+// DGP has no direct runtime dependencies on any of the conflicting dependencies, and Gradle has
+// constraints that force the transitive dependencies to match the embedded versions.
+// Unfortunately this means there is no way of testing if this config works, or can be safely removed.
+// It was originally added because in previous versions DGP did have a direct dependency on
+// kotlin-stdlib, but the buildscript has been re-written to correct this, meaning there are no
+// longer conflicting dependencies.
+//
+// These exclusions have been kept due to an abundance of caution.
+//
+// See also:
+// - https://youtrack.jetbrains.com/issue/KT-41142
+// - https://github.com/JetBrains/kotlin/blob/2f41a05651e4709fcb6984bbac769af8e8f63935/libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/SimpleKotlinGradleIT.kt#L180
+// - https://github.com/Kotlin/dokka/pull/2570
+fun Project.excludeGradleEmbeddedDependencies(sourceSet: NamedDomainObjectProvider<SourceSet>) {
+    val excludeAction = Action<Configuration> {
+        dependencies
+            .withType<ModuleDependency>()
+            .configureEach {
+                exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib")
+                exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib-jdk7")
+                exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib-jdk8")
+                exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib-common")
+                exclude(group = "org.jetbrains.kotlin", module = "kotlin-reflect")
+                exclude(group = "org.jetbrains.kotlin", module = "kotlin-script-runtime")
+            }
+    }
+
+    sourceSet.configure {
+        configurations.named(implementationConfigurationName, excludeAction)
+        configurations.named(apiConfigurationName, excludeAction)
+        configurations.named(runtimeOnlyConfigurationName, excludeAction)
+    }
+}

build.gradle.kts

@@ -6,8 +6,8 @@ plugins {
     id("dokkabuild.base")
 }
 
-val publishedIncludedBuilds = listOf("runner-cli", "runner-gradle-plugin-classic", "runner-maven-plugin")
-val gradlePluginIncludedBuilds = listOf("runner-gradle-plugin-classic")
+val publishedIncludedBuilds = listOf("runner-cli", "dokka-gradle-plugin", "runner-maven-plugin")
+val gradlePluginIncludedBuilds = listOf("dokka-gradle-plugin")
 
 addDependencyOnSameTasksOfIncludedBuilds("assemble", "build", "clean", "check")
 
@@ -18,7 +18,7 @@ registerParentGroupTasks(
         "publishAllPublicationsToSnapshotRepository",
         "publishAllPublicationsToSpaceDevRepository",
         "publishAllPublicationsToSpaceTestRepository",
-        "publishToMavenLocal"
+        "publishToMavenLocal",
     )
 ) {
     it.name in publishedIncludedBuilds
@@ -27,7 +27,7 @@ registerParentGroupTasks(
 registerParentGroupTasks(
     "gradle plugin", taskNames = listOf(
         "publishPlugins",
-        "validatePlugins"
+        "validatePlugins",
     )
 ) {
     it.name in gradlePluginIncludedBuilds
@@ -37,15 +37,15 @@ registerParentGroupTasks(
     "bcv", taskNames = listOf(
         "apiDump",
         "apiCheck",
-        "apiBuild"
+        "apiBuild",
     )
 ) {
     it.name in publishedIncludedBuilds
 }
 
 registerParentGroupTasks(
     "verification", taskNames = listOf(
-        "test"
+        "test",
     )
 )
 

dokka-integration-tests/gradle/build.gradle.kts

@@ -47,7 +47,7 @@ dependencies {
     devPublication("org.jetbrains.dokka:plugin-templating:$dokkaVersion")
     devPublication("org.jetbrains.dokka:plugin-versioning:$dokkaVersion")
 
-    devPublication("org.jetbrains.dokka:runner-gradle-plugin-classic:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:dokka-gradle-plugin:$dokkaVersion")
 }
 
 kotlin {

dokka-integration-tests/settings.gradle.kts

@@ -38,7 +38,7 @@ dependencyResolutionManagement {
     }
 }
 
-includeBuild("../dokka-runners/runner-gradle-plugin-classic")
+includeBuild("../dokka-runners/dokka-gradle-plugin")
 includeBuild("../dokka-runners/runner-maven-plugin")
 includeBuild("../dokka-runners/runner-cli")
 includeBuild("../.") // depend on the root project, so integration-tests can depend on projects in `dokka-subprojects/*`