misc: upgrade to Dokka 2.0.0 (#1284)

Author: lauzadis

.changes/50a9ce20-c4d7-4952-8fad-f9ffb38c9259.json

@@ -0,0 +1,5 @@
+{
+    "id": "50a9ce20-c4d7-4952-8fad-f9ffb38c9259",
+    "type": "misc",
+    "description": "Upgrade to Dokka 2.0.0"
+}

.editorconfig

@@ -9,4 +9,4 @@ 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

build.gradle.kts

@@ -18,13 +18,13 @@ buildscript {
 }
 
 plugins {
-    alias(libs.plugins.dokka)
+    `dokka-convention`
     alias(libs.plugins.kotlinx.binary.compatibility.validator)
+    alias(libs.plugins.aws.kotlin.repo.tools.artifactsizemetrics)
     // ensure the correct version of KGP ends up on our buildscript classpath
     // since build-plugins also has <some> version in its dependency closure
-    alias(libs.plugins.kotlin.multiplatform) apply false
-    alias(libs.plugins.kotlin.jvm) apply false
-    alias(libs.plugins.aws.kotlin.repo.tools.artifactsizemetrics)
+    id(libs.plugins.kotlin.multiplatform.get().pluginId) apply false
+    id(libs.plugins.kotlin.jvm.get().pluginId) apply false
 }
 
 artifactSizeMetrics {
@@ -40,35 +40,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)
-    }
-
     if (rootProject.typedProp<Boolean>("kotlinWarningsAsErrors") == true) {
         tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
-            kotlinOptions.allWarningsAsErrors = true
+            compilerOptions.allWarningsAsErrors = true
         }
     }
 
@@ -90,27 +64,18 @@ allprojects {
 }
 
 // configure the root multimodule docs
-tasks.dokkaHtmlMultiModule.configure {
+dokka {
     moduleName.set("Smithy 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)
+    dokkaPublications.html {
+        includes.from(
+            rootProject.file("docs/dokka-presets/README.md"),
+        )
     }
+}
 
-    includes.from(
-        // NOTE: these get concatenated
-        rootProject.file("docs/dokka-presets/README.md"),
-    )
-
-    val excludeFromDocumentation = listOf(
-        project(":runtime:testing"),
-        project(":runtime:smithy-test"),
-    )
-    removeChildTasks(excludeFromDocumentation)
+dependencies {
+    dokka(project(":runtime"))
 }
 
 // Publishing
@@ -121,6 +86,7 @@ val lintPaths = listOf(
     "**/*.{kt,kts}",
     "!**/generated-src/**",
     "!**/smithyprojections/**",
+    "!**/build/**",
 )
 
 configureLinting(lintPaths)

buildSrc/build.gradle.kts

@@ -0,0 +1,13 @@
+plugins {
+    `kotlin-dsl`
+}
+
+repositories {
+    mavenCentral()
+    gradlePluginPortal()
+}
+
+dependencies {
+    implementation(libs.dokka.gradle.plugin)
+    implementation(libs.kotlin.gradle.plugin)
+}

buildSrc/settings.gradle.kts

@@ -0,0 +1,9 @@
+rootProject.name = "buildSrc"
+
+dependencyResolutionManagement {
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+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"),
+        )
+
+        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)
+    }
+}
+
+dependencies {
+    dokkaPlugin(project(":dokka-smithy"))
+}

codegen/smithy-aws-kotlin-codegen/build.gradle.kts

@@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-    alias(libs.plugins.kotlin.jvm)
+    id(libs.plugins.kotlin.jvm.get().pluginId)
     jacoco
     `maven-publish`
 }

codegen/smithy-kotlin-codegen-testutils/build.gradle.kts

@@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-    alias(libs.plugins.kotlin.jvm)
+    id(libs.plugins.kotlin.jvm.get().pluginId)
     jacoco
     `maven-publish`
 }

codegen/smithy-kotlin-codegen/build.gradle.kts

@@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
-    alias(libs.plugins.kotlin.jvm)
+    id(libs.plugins.kotlin.jvm.get().pluginId)
     jacoco
     `maven-publish`
 }

docs/dokka-presets/assets/aws_logo_white_59x35.png

@@ -4,45 +4,29 @@
  */
 
 :root {
-    --aws-color-dark: #232f3e;
-    --horizontal-spacing-for-content: 16px;
-    --default-font-family: JetBrains Sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI,Roboto, Oxygen, Ubuntu,Cantarell, Droid Sans, Helvetica Neue, Arial, sans-serif;
+    --color-background-nav: #232f3e;
+    --dokka-logo-height: 60px;
+    --dokka-logo-width: 90px;
 }
 
-.menu-toggle {
-    background: none;
-}
-
-.menu-toggle:focus {
-    outline: 2px solid #fff; /* White outline */
-    outline-offset: 2px;    /* Space between the outline and the button */
-}
-
-#pages-search:focus {
-    outline: revert;
-}
-
-/* copied from Dokka except for background-color attribute */
-.navigation {
-    display: flex;
-    justify-content: space-between;
-
-    color: #fff;
-    background-color: var(--aws-color-dark);
-    font-family: var(--default-font-family);
-    letter-spacing: -0.1px;
-
-    /* Reset margin and use padding for border */
-    margin-left: 0;
-    margin-right: 0;
-    padding: 10px var(--horizontal-spacing-for-content);
-
-    z-index: 4;
+.skip-to-content {
+    position: absolute; /* Remove from normal flow */
+    top: 0; /* Position off-screen */
+    left: 0;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    opacity: 0;
+    z-index: -1; /* Ensure it's not visible */
 }
 
-/* Styles for section tabs like "Types" and "Functions" */
-.section-tab:focus, .section-tab:active {
-    outline: 2px solid var(--active-tab-border-color); /* The color appears unresolved, but it is defined in Dokka style sheets */
+.skip-to-content:focus,
+.skip-to-content:active {
+    position: static; /* Restore to normal flow when focused */
+    width: auto;
+    height: auto;
+    opacity: 1;
+    z-index: 999; /* Ensure it's on top */
 }
 
 /*
@@ -55,44 +39,45 @@
 .symbol {
     overflow-wrap: break-word;
 }
-
 .keyValue {
     display: block;
 }
 
-/*
-    Disable the playground run button for generated samples
-    https://github.com/Kotlin/dokka/issues/3041
-*/
-div .compiler-info, .fold-button, .run-button {
-    display: none;
+/* FIXME Taken from Dokka mainline. Remove these styles once Dokka 2.1.0 is released. */
+.toc--skip-link {
+    background-color: #458cff;
+    color: #fff;
+    font: 400 13px/24px Inter, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, Oxygen, Droid Sans, Helvetica Neue, Arial;
+    margin-top: 36px;
+    padding: 1px;
+    position: absolute;
+    z-index: 100;
 }
 
-.skip-to-content {
-    width: 1px;
-    height: 1px;
-    overflow: hidden;
-    opacity: 0;
+.toc--skip-link:not(:focus) {
+    overflow: hidden !important;
+    clip: rect(1px, 1px, 1px, 1px) !important;
+    border: 0 !important;
+    height: 1px !important;
+    padding: 0 !important;
+    width: 1px !important;
 }
 
-.skip-to-content:focus,
-.skip-to-content:active {
-    width: auto;
-    height: auto;
-    opacity: 1;
-    z-index: 999; /* Ensure the skip link is on top of other content */
+.toc--skip-link:focus {
+    outline: 4px solid rgb(48, 127, 255, 0.5);
+    outline-offset: 0;
+}
+
+.sidebar > .toc--skip-link {
+    margin-top: 0;
 }
 
-.aws-toggle-content-btn {
-    font-size: 24px;
-    background: none;
-    border: none;
-    cursor: pointer;
-    padding: 8px;
+.toc--part_hidden > .toc--row > .toc--button ~ .toc--skip-link {
+    display: none;
 }
 
-@media (max-width: 550px) {
-    .content[data-togglable] {
+@media (max-width: 899px) {
+    .toc--skip-link {
         display: none;
     }
 }