misc: upgrade to Dokka 2.0.0

.changes/fb53db86-ba89-44ae-86e3-1c85abb9c217.json

@@ -0,0 +1,5 @@
+{
+    "id": "fb53db86-ba89-44ae-86e3-1c85abb9c217",
+    "type": "misc",
+    "description": "Upgrade to Dokka 2.0.0"
+}

.github/workflows/release-readiness.yml

@@ -38,6 +38,7 @@ jobs:
           repository: 'smithy-lang/smithy-kotlin'
 
       - name: Check for smithy-kotlin unreleased changes
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'ready-for-release') }}
         run: |
           echo "aws-sdk-kotlin branch: $GITHUB_HEAD_REF"
 

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)
@@ -85,7 +84,6 @@ smithyBuild {
     val basePackage = "aws.sdk.kotlin.runtime.auth.credentials.internal"
 
     projections {
-
         // generate an sts client
         create("sts-credentials-provider") {
             imports = listOf(
@@ -243,9 +241,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/dokka-module-and-package-docs.html
-        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()
 
@@ -148,6 +87,7 @@ val lintPaths = listOf(
     "!**/generated/ksp/**",
     "!**/kspCaches/**",
     "!**/smithyprojections/**",
+    "!**/build/**",
 )
 
 configureLinting(lintPaths)

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,60 @@
+import kotlin.text.set
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+dokka {
+    val sdkVersion: String by project
+    moduleVersion.set(sdkVersion)
+
+    dokkaGeneratorIsolation = ProcessIsolation {
+        maxHeapSize = "4g"
+    }
+
+    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"),
+        )
+
+        templatesDir.set(rootProject.file("docs/dokka-presets/templates"))
+
+        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
 }