misc: Upgrade to Dokka 2.0

.editorconfig

@@ -9,4 +9,7 @@ ktlint_standard_backing-property-naming = disabled
 # enable trailing commas per JetBrains recommendation
 # (https://kotlinlang.org/docs/coding-conventions.html#trailing-commas)
 ij_kotlin_allow_trailing_comma_on_call_site = true
-ij_kotlin_allow_trailing_comma = true
+ij_kotlin_allow_trailing_comma = true
+
+[buildSrc/build/**]
+ktlint = disabled

aws-runtime/aws-config/build.gradle.kts

@@ -5,7 +5,6 @@
 import aws.sdk.kotlin.gradle.codegen.dsl.generateSmithyProjections
 import aws.sdk.kotlin.gradle.codegen.dsl.smithyKotlinPlugin
 import aws.sdk.kotlin.gradle.codegen.smithyKotlinProjectionSrcDir
-import org.jetbrains.dokka.gradle.DokkaTaskPartial
 
 plugins {
     alias(libs.plugins.aws.kotlin.repo.tools.smithybuild)
@@ -83,7 +82,6 @@ smithyBuild {
     val basePackage = "aws.sdk.kotlin.runtime.auth.credentials.internal"
 
     projections {
-
         // generate an sts client
         create("sts-credentials-provider") {
             imports = listOf(
@@ -241,9 +239,12 @@ smithyBuild.projections.all {
     }
 }
 
-// suppress internal generated clients
-tasks.named<DokkaTaskPartial>("dokkaHtmlPartial") {
-    dependsOn(tasks.generateSmithyProjections)
+// Suppress internally-generated clients
+dokka {
+    tasks.dokkaGenerateModuleHtml {
+        dependsOn(tasks.generateSmithyProjections)
+    }
+
     dokkaSourceSets.configureEach {
         perPackageOption {
             matchingRegex.set(""".*\.internal.*""")

aws-runtime/build.gradle.kts

@@ -9,7 +9,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 description = "AWS client runtime support for generated service clients"
 
 plugins {
-    alias(libs.plugins.dokka)
+    `dokka-convention`
     alias(libs.plugins.kotlinx.binary.compatibility.validator)
     alias(libs.plugins.aws.kotlin.repo.tools.kmp) apply false
     jacoco
@@ -28,7 +28,6 @@ subprojects {
 
     apply {
         plugin("org.jetbrains.kotlin.multiplatform")
-        plugin("org.jetbrains.dokka")
         plugin(libraries.plugins.aws.kotlin.repo.tools.kmp.get().pluginId)
     }
 
@@ -61,10 +60,6 @@ subprojects {
         listOf("kotlin.RequiresOptIn").forEach { languageSettings.optIn(it) }
     }
 
-    dependencies {
-        dokkaPlugin(project(":dokka-aws"))
-    }
-
     tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
         compilerOptions {
             jvmTarget.set(JvmTarget.JVM_1_8)
@@ -77,3 +72,11 @@ subprojects {
         }
     }
 }
+
+// Configure Dokka for subprojects
+dependencies {
+    subprojects.forEach {
+        it.plugins.apply("dokka-convention") // Apply the Dokka conventions plugin to the subproject
+        dokka(project(it.path)) // Aggregate the subprojects' generated documentation
+    }
+}

build.gradle.kts

@@ -5,7 +5,6 @@
 import aws.sdk.kotlin.gradle.dsl.configureLinting
 import aws.sdk.kotlin.gradle.dsl.configureNexus
 import aws.sdk.kotlin.gradle.util.typedProp
-import java.net.URL
 
 buildscript {
     // NOTE: buildscript classpath for the root project is the parent classloader for the subprojects, we
@@ -18,10 +17,10 @@ buildscript {
 }
 
 plugins {
-    alias(libs.plugins.dokka)
+    `dokka-convention`
     // ensure the correct version of KGP ends up on our buildscript classpath
-    alias(libs.plugins.kotlin.multiplatform) apply false
-    alias(libs.plugins.kotlin.jvm) apply false
+    id(libs.plugins.kotlin.multiplatform.get().pluginId) apply false
+    id(libs.plugins.kotlin.jvm.get().pluginId) apply false
     alias(libs.plugins.aws.kotlin.repo.tools.artifactsizemetrics)
 }
 
@@ -39,67 +38,9 @@ val testJavaVersion = typedProp<String>("test.java.version")?.let {
 }
 
 allprojects {
-    tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaTask>().configureEach {
-        val sdkVersion: String by project
-        moduleVersion.set(sdkVersion)
-
-        val year = java.time.LocalDate.now().year
-        val pluginConfigMap = mapOf(
-            "org.jetbrains.dokka.base.DokkaBase" to """
-                {
-                    "customStyleSheets": [
-                        "${rootProject.file("docs/dokka-presets/css/logo-styles.css")}",
-                        "${rootProject.file("docs/dokka-presets/css/aws-styles.css")}"
-                    ],
-                    "customAssets": [
-                        "${rootProject.file("docs/dokka-presets/assets/logo-icon.svg")}",
-                        "${rootProject.file("docs/dokka-presets/assets/aws_logo_white_59x35.png")}",
-                        "${rootProject.file("docs/dokka-presets/scripts/accessibility.js")}"
-                    ],
-                    "footerMessage": "© $year, Amazon Web Services, Inc. or its affiliates. All rights reserved.",
-                    "separateInheritedMembers" : true,
-                    "templatesDir": "${rootProject.file("docs/dokka-presets/templates")}"
-                }
-            """,
-        )
-        pluginsMapConfiguration.set(pluginConfigMap)
-    }
-
-    tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial>().configureEach {
-        // each module can include their own top-level module documentation
-        // see https://kotlinlang.org/docs/kotlin-doc.html#module-and-package-documentation
-        if (project.file("API.md").exists()) {
-            dokkaSourceSets.configureEach {
-                includes.from(project.file("API.md"))
-            }
-        }
-
-        dokkaSourceSets.configureEach {
-            samples.from(project.file("samples").path, project.file("generated-src/samples").path)
-        }
-
-        val smithyKotlinPackageListUrl: String? by project
-        val smithyKotlinDocBaseUrl: String? by project
-
-        // Configure Dokka to link to smithy-kotlin types if specified in properties
-        // These optional properties are supplied api the api docs build job but are unneeded otherwise
-        smithyKotlinDocBaseUrl.takeUnless { it.isNullOrEmpty() }?.let { docBaseUrl ->
-            val expandedDocBaseUrl = docBaseUrl.replace("\$smithyKotlinRuntimeVersion", libs.versions.smithy.kotlin.runtime.version.get())
-            dokkaSourceSets.configureEach {
-                externalDocumentationLink {
-                    url.set(URL(expandedDocBaseUrl))
-
-                    smithyKotlinPackageListUrl
-                        .takeUnless { it.isNullOrEmpty() }
-                        ?.let { packageListUrl.set(URL(it)) }
-                }
-            }
-        }
-    }
-
     if (rootProject.typedProp<Boolean>("kotlinWarningsAsErrors") == true) {
         tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
-            kotlinOptions.allWarningsAsErrors = true
+            compilerOptions.allWarningsAsErrors = true
         }
     }
 
@@ -118,26 +59,24 @@ allprojects {
     tasks.register<DependencyReportTask>("allDeps") { }
 }
 
-project.afterEvaluate {
-    // configure the root multimodule docs
-    tasks.dokkaHtmlMultiModule.configure {
-        moduleName.set("AWS SDK for Kotlin")
-
-        // Output subprojects' docs to <docs-base>/project-name/* instead of <docs-base>/path/to/project-name/*
-        // This is especially important for inter-repo linking (e.g., via externalDocumentationLink) because the
-        // package-list doesn't contain enough project path information to indicate where modules' documentation are
-        // located.
-        fileLayout.set { parent, child ->
-            parent.outputDirectory.dir(child.moduleName)
-        }
+// Configure root module's documentation
+dokka {
+    moduleName.set("AWS SDK for Kotlin")
 
+    dokkaPublications.html {
         includes.from(
-            // NOTE: these get concatenated
             rootProject.file("docs/dokka-presets/README.md"),
         )
     }
 }
 
+// Aggregate subprojects' documentation
+dependencies {
+    dokka(project(":aws-runtime"))
+    dokka(project(":services"))
+    dokka(project(":hll"))
+}
+
 // Publishing
 configureNexus()
 

buildSrc/build.gradle.kts

@@ -1,7 +1,14 @@
 plugins {
     alias(libs.plugins.kotlin.jvm)
+    `kotlin-dsl`
 }
 
 repositories {
     mavenCentral()
+    gradlePluginPortal()
+}
+
+dependencies {
+    implementation(libs.dokka.gradle.plugin)
+    implementation(libs.kotlin.gradle.plugin)
 }

buildSrc/settings.gradle.kts

@@ -1,3 +1,5 @@
+rootProject.name = "buildSrc"
+
 dependencyResolutionManagement {
     versionCatalogs {
         create("libs") {

buildSrc/src/main/kotlin/dokka-convention.gradle.kts

@@ -0,0 +1,54 @@
+import kotlin.text.set
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+dokka {
+    val sdkVersion: String by project
+    moduleVersion.set(sdkVersion)
+
+    pluginsConfiguration.html {
+        customStyleSheets.from(
+            rootProject.file("docs/dokka-presets/css/aws-styles.css"),
+        )
+
+        customAssets.from(
+            rootProject.file("docs/dokka-presets/assets/logo-icon.svg"),
+            rootProject.file("docs/dokka-presets/scripts/accessibility.js"),
+        )
+
+        footerMessage.set("© ${java.time.LocalDate.now().year}, Amazon Web Services, Inc. or its affiliates. All rights reserved.")
+        separateInheritedMembers.set(true)
+    }
+
+    // each module can include their own top-level module documentation
+    // see https://kotlinlang.org/docs/kotlin-doc.html#module-and-package-documentation
+    if (project.file("API.md").exists()) {
+        dokkaSourceSets.configureEach {
+            includes.from(project.file("API.md"))
+        }
+    }
+
+    dokkaSourceSets.configureEach {
+        // Only configure samples on `commonMain`.
+        // Fixes compiler warnings: "Source sets 'common' and 'desktop' have the common sample roots. In Dokka K2 it will be an error."
+        if (name == "commonMain") {
+            samples.from(project.file("samples").path, project.file("generated-src/samples").path)
+        }
+    }
+
+    // Configure Dokka to link to smithy-kotlin types
+    dokkaSourceSets.configureEach {
+        externalDocumentationLinks {
+            create("smithy-kotlin") {
+                val smithyKotlinRuntimeVersion = versionCatalogs.named("libs").findVersion("smithy-kotlin-runtime-version").get()
+                url("https://sdk.amazonaws.com/kotlin/api/smithy-kotlin/api/$smithyKotlinRuntimeVersion")
+            }
+        }
+    }
+}
+
+dependencies {
+    dokkaPlugin(project(":dokka-aws"))
+}

codegen/aws-sdk-codegen/build.gradle.kts

@@ -10,7 +10,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
  * SPDX-License-Identifier: Apache-2.0
  */
 plugins {
-    alias(libs.plugins.kotlin.jvm)
+    id(libs.plugins.kotlin.jvm.get().pluginId)
     jacoco
 }