build config: Use buildSrc convention plugins to configure the Dokka subprojects

build.gradle.kts

@@ -1,76 +1,21 @@
-import org.jetbrains.*
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import org.jetbrains.ValidatePublications
+import org.jetbrains.publicationChannels
 
 plugins {
-    kotlin("jvm") apply false
-    id("java")
-    id("org.jetbrains.dokka") version "1.7.20"
+    org.jetbrains.conventions.base
+    id("org.jetbrains.dokka")
     id("io.github.gradle-nexus.publish-plugin")
-}
-
-val dokka_version: String by project
-
-allprojects {
-    configureDokkaVersion()
 
-    group = "org.jetbrains.dokka"
-    version = dokka_version
-
-
-    val language_version: String by project
-    tasks.withType(KotlinCompile::class).all {
-        kotlinOptions {
-            freeCompilerArgs = freeCompilerArgs + listOf(
-                "-opt-in=kotlin.RequiresOptIn",
-                "-Xjsr305=strict",
-                "-Xskip-metadata-version-check",
-                // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4)
-                "-Xsuppress-version-warnings"
-            )
-            allWarningsAsErrors = true
-            languageVersion = language_version
-            apiVersion = language_version
-            jvmTarget = "1.8"
-        }
-    }
-
-    repositories {
-        mavenCentral()
-    }
+    id("org.jetbrains.kotlinx.binary-compatibility-validator")
 }
 
-subprojects {
-    apply {
-        plugin("org.jetbrains.kotlin.jvm")
-        plugin("java")
-        plugin("signing")
-        plugin("org.jetbrains.dokka")
-    }
-
-    // Gradle metadata
-    java {
-        @Suppress("UnstableApiUsage")
-        withSourcesJar()
-        targetCompatibility = JavaVersion.VERSION_1_8
-    }
-
-    tasks {
-        val dokkaOutputDir = "$buildDir/dokka"
+val dokka_version: String by project
 
-        dokkaHtml {
-            onlyIf { !isLocalPublication }
-            outputDirectory.set(file(dokkaOutputDir))
-        }
+group = "org.jetbrains.dokka"
+version = dokka_version
 
-        register<Jar>("javadocJar") {
-            archiveClassifier.set("javadoc")
-            dependsOn(dokkaHtml)
-            from(dokkaOutputDir)
-        }
-    }
-}
 
-println("Publication version: $dokka_version")
+logger.lifecycle("Publication version: $dokka_version")
 tasks.register<ValidatePublications>("validatePublications")
 
 nexusPublishing {
@@ -82,8 +27,28 @@ nexusPublishing {
     }
 }
 
-tasks.maybeCreate("dokkaPublish").run {
+val dokkaPublish by tasks.registering {
     if (publicationChannels.any { it.isMavenRepository() }) {
         finalizedBy(tasks.named("closeAndReleaseSonatypeStagingRepository"))
     }
 }
+
+apiValidation {
+    // note that subprojects are ignored by their name, not their path https://github.com/Kotlin/binary-compatibility-validator/issues/16
+    ignoredProjects += setOf(
+        // NAME                    PATH
+        "search-component",    // :plugins:search-component
+        "frontend",            // :plugins:base:frontend
+
+        "kotlin-analysis",     // :kotlin-analysis
+        "compiler-dependency", // :kotlin-analysis:compiler-dependency
+        "intellij-dependency", // :kotlin-analysis:intellij-dependency
+
+        "integration-tests",   // :integration-tests
+        "gradle",              // :integration-tests:gradle
+        "cli",                 // :integration-tests:cli
+        "maven",               // integration-tests:maven
+
+        "test-utils",          // :test-utils
+    )
+}

buildSrc/build.gradle.kts

@@ -1,3 +1,5 @@
+import java.util.Properties
+
 plugins {
     `kotlin-dsl`
 }
@@ -6,8 +8,23 @@ repositories {
     gradlePluginPortal()
 }
 
+// TODO define versions in Gradle Version Catalog https://github.com/Kotlin/dokka/pull/2884
+val properties = file("../gradle.properties").inputStream().use {
+    Properties().apply { load(it) }
+}
+
+val kotlinVersion = properties["kotlin_version"]
+
 dependencies {
-    implementation("com.github.jengelman.gradle.plugins:shadow:2.0.4")
-    implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.10.1")
+    // Import Gradle Plugins that will be used in the buildSrc pre-compiled script plugins, and any `build.gradle.kts`
+    // files in the project.
+    // Use their Maven coordinates (plus versions), not Gradle plugin IDs!
+    // This should be the only place that Gradle plugin versions are defined, so they are aligned across all build scripts
+
+    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    implementation("gradle.plugin.com.github.johnrengelman:shadow:7.1.2")
+    implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.12.1")
     implementation("io.github.gradle-nexus:publish-plugin:1.1.0")
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.7.10")
+    implementation("com.gradle.publish:plugin-publish-plugin:0.20.0")
 }

buildSrc/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "buildSrc"

buildSrc/src/main/kotlin/org/jetbrains/conventions/base.gradle.kts

@@ -0,0 +1,12 @@
+package org.jetbrains.conventions
+
+plugins {
+    base
+}
+
+// common Gradle configuration that should be applied to all projects
+
+if (project != rootProject) {
+    project.group = rootProject.group
+    project.version = rootProject.version
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka-integration-test.gradle.kts

@@ -0,0 +1,75 @@
+package org.jetbrains.conventions
+
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+import org.gradle.api.tasks.testing.logging.TestLogEvent
+
+plugins {
+    id("org.jetbrains.conventions.kotlin-jvm")
+}
+
+val integrationTestSourceSet = sourceSets.create("integrationTest") {
+    compileClasspath += sourceSets.main.get().output
+    runtimeClasspath += sourceSets.main.get().output
+}
+
+val integrationTestImplementation by configurations.getting {
+    extendsFrom(configurations.implementation.get())
+}
+
+val integrationTestRuntimeOnly by configurations.getting {
+    extendsFrom(configurations.runtimeOnly.get())
+}
+
+/**
+ * Dokka's integration test task is not cacheable because the HTML outputs
+ * it produces when running the tests are used for showcasing resulting documentation,
+ * which does not work well with caching.
+ *
+ * At the moment there are two problems that do not allow to make it cacheable:
+ *
+ * 1. The task's inputs are such that changes in Dokka's code do not invalidate the cache,
+ *    because it is run with the same version of Dokka (`"DOKKA_VERSION"`) on the same
+ *    test project inputs.
+ * 2. The tests generate HTML output which is then used to showcase documentation.
+ *    The outputs are usually copied to a location from which it will be served.
+ *    However, if the test is cacheable, it produces no outputs, so no documentation
+ *    to showcase. It needs to be broken into two separate tasks: one cacheable for running
+ *    the tests and producing HTML output, and another non-cacheable for copying the output.
+ *
+ * @see [org.jetbrains.dokka.it.TestOutputCopier] for more details on showcasing documentation
+ */
+@DisableCachingByDefault(because = "Contains incorrect inputs/outputs configuration, see the KDoc for details")
+abstract class NonCacheableIntegrationTest : Test()
+
+val integrationTest by tasks.registering(NonCacheableIntegrationTest::class) {
+    maxHeapSize = "2G"
+    description = "Runs integration tests."
+    group = "verification"
+    useJUnit()
+
+    testClassesDirs = integrationTestSourceSet.output.classesDirs
+    classpath = integrationTestSourceSet.runtimeClasspath
+
+    setForkEvery(1)
+    project.properties["dokka_integration_test_parallelism"]?.toString()?.toIntOrNull()?.let { parallelism ->
+        maxParallelForks = parallelism
+    }
+    environment(
+        "isExhaustive",
+        project.properties["dokka_integration_test_is_exhaustive"]?.toString()?.toBoolean()
+            ?: System.getenv("DOKKA_INTEGRATION_TEST_IS_EXHAUSTIVE")?.toBoolean()
+            ?: false.toString()
+    )
+
+    testLogging {
+        exceptionFormat = TestExceptionFormat.FULL
+        events(TestLogEvent.SKIPPED, TestLogEvent.FAILED)
+        showExceptions = true
+        showCauses = true
+        showStackTraces = true
+    }
+}
+
+tasks.check {
+    dependsOn(integrationTest)
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka.gradle.kts

@@ -0,0 +1,13 @@
+package org.jetbrains.conventions
+
+import org.gradle.kotlin.dsl.invoke
+import org.jetbrains.isLocalPublication
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+tasks.dokkaHtml {
+    onlyIf { !isLocalPublication }
+    outputDirectory.set(layout.buildDirectory.dir("dokka").map { it.asFile })
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts

@@ -0,0 +1,35 @@
+package org.jetbrains.conventions
+
+import org.jetbrains.configureDokkaVersion
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    id("org.jetbrains.conventions.base")
+    kotlin("jvm")
+}
+
+configureDokkaVersion()
+
+val language_version: String by project
+
+tasks.withType<KotlinCompile>().configureEach {
+    kotlinOptions {
+        freeCompilerArgs = freeCompilerArgs + listOf(
+            "-opt-in=kotlin.RequiresOptIn",
+            "-Xjsr305=strict",
+            "-Xskip-metadata-version-check",
+            // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4)
+            "-Xsuppress-version-warnings"
+        )
+        allWarningsAsErrors = true
+        languageVersion = language_version
+        apiVersion = language_version
+        jvmTarget = "1.8"
+    }
+}
+
+// Gradle metadata
+java {
+    withSourcesJar()
+    targetCompatibility = JavaVersion.VERSION_1_8
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/maven-publish.gradle.kts

@@ -0,0 +1,30 @@
+package org.jetbrains.conventions
+
+plugins {
+    id("org.jetbrains.conventions.base")
+    `maven-publish`
+    signing
+    id("org.jetbrains.conventions.dokka")
+}
+
+val javadocJar by tasks.registering(Jar::class) {
+    group = JavaBasePlugin.DOCUMENTATION_GROUP
+    description = "Assembles a Javadoc JAR using Dokka HTML"
+    archiveClassifier.set("javadoc")
+    from(tasks.dokkaHtml)
+}
+
+publishing {
+    repositories {
+        // Publish to a project-local Maven directory, for verification. To test, run:
+        // ./gradlew publishAllPublicationsToMavenProjectLocalRepository
+        // and check $rootDir/build/maven-project-local
+        maven(rootProject.layout.buildDirectory.dir("maven-project-local")) {
+            name = "MavenProjectLocal"
+        }
+    }
+
+    publications.withType<MavenPublication>().configureEach {
+        artifact(javadocJar)
+    }
+}

buildSrc/src/main/kotlin/org/jetbrains/publication.kt

@@ -2,9 +2,13 @@ package org.jetbrains
 
 import com.github.jengelman.gradle.plugins.shadow.ShadowExtension
 import org.gradle.api.Project
+import org.gradle.api.plugins.JavaBasePlugin
 import org.gradle.api.publish.PublishingExtension
 import org.gradle.api.publish.maven.MavenPublication
 import org.gradle.api.publish.maven.tasks.PublishToMavenRepository
+import org.gradle.api.tasks.TaskContainer
+import org.gradle.api.tasks.TaskProvider
+import org.gradle.api.tasks.bundling.Jar
 import org.gradle.kotlin.dsl.*
 import org.gradle.plugins.signing.SigningExtension
 import org.jetbrains.DokkaPublicationChannel.*
@@ -33,7 +37,6 @@ fun Project.registerDokkaArtifactPublication(publicationName: String, configure:
                         artifact(tasks["sourcesJar"])
                     }
                 }
-                artifact(tasks["javadocJar"])
                 configurePom("Dokka ${project.name}")
             }
         }
@@ -42,7 +45,6 @@ fun Project.registerDokkaArtifactPublication(publicationName: String, configure:
     configureSpacePublicationIfNecessary(publicationName)
     configureSonatypePublicationIfNecessary(publicationName)
     createDokkaPublishTaskIfNecessary()
-    registerBinaryCompatibilityCheck(publicationName)
 }
 
 fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {

core/build.gradle.kts

@@ -2,7 +2,8 @@ import org.jetbrains.dokkaVersion
 import org.jetbrains.registerDokkaArtifactPublication
 
 plugins {
-    `maven-publish`
+    org.jetbrains.conventions.`kotlin-jvm`
+    org.jetbrains.conventions.`maven-publish`
 }
 
 dependencies {

core/content-matcher-test-utils/build.gradle.kts

@@ -1,3 +1,7 @@
+plugins {
+    org.jetbrains.conventions.`kotlin-jvm`
+}
+
 dependencies {
     implementation(project(":core:test-api"))
     implementation(kotlin("stdlib-jdk8"))