wip: centralize Dokka configuration and plugins into repo tools

build-plugins/build-support/build.gradle.kts

@@ -25,6 +25,8 @@ dependencies {
     implementation("aws.sdk.kotlin:s3:1.1.+")
     implementation("aws.sdk.kotlin:cloudwatch:1.1.+")
     testImplementation(libs.junit.jupiter)
+    compileOnly(libs.dokka.base)
+    compileOnly(libs.dokka.core)
 }
 
 gradlePlugin {

build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/DokkaConventionsPlugin.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.sdk.kotlin.gradle.dokka
+
+import aws.sdk.kotlin.gradle.dokka.extensions.FilterInternalApis
+import aws.sdk.kotlin.gradle.dokka.extensions.NoOpSearchbarDataInstaller
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
+
+class DokkaConventionsPlugin : DokkaPlugin() {
+    init {
+        println("${this::class.qualifiedName} loaded!")
+    }
+
+    val dokkaBase by lazy { plugin<DokkaBase>() }
+
+    val filterInternalApis by extending {
+        dokkaBase.preMergeDocumentableTransformer providing ::FilterInternalApis
+    }
+
+    // FIXME Re-enable search once Dokka addresses performance issues
+    // https://github.com/Kotlin/dokka/issues/2741
+    val disableSearch by extending {
+        dokkaBase.htmlPreprocessors providing ::NoOpSearchbarDataInstaller override dokkaBase.baseSearchbarDataInstaller
+    }
+
+    @DokkaPluginApiPreview
+    override fun pluginApiPreviewAcknowledgement() = PluginApiPreviewAcknowledgement
+}

build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/extensions/FilterInternalApis.kt

@@ -0,0 +1,41 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package aws.sdk.kotlin.gradle.dokka.extensions
+
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+
+/**
+ * Filters out anything annotated with `InternalApi` or `InternalSdkApi`
+ */
+class FilterInternalApis(context: DokkaContext) : SuppressedByConditionDocumentableFilterTransformer(context) {
+    override fun shouldBeSuppressed(d: Documentable): Boolean {
+        val isInternal = when (d) {
+            is DClass -> d.isInternal()
+            is DObject -> d.isInternal()
+            is DTypeAlias -> d.isInternal()
+            is DFunction -> d.isInternal()
+            is DProperty -> d.isInternal()
+            is DEnum -> d.isInternal()
+            is DEnumEntry -> d.isInternal()
+            is DTypeParameter -> d.isInternal()
+            else -> false
+        }
+
+        if (isInternal) context.logger.warn("Suppressing internal element '${d.name}'")
+
+        return isInternal
+    }
+}
+
+private val internalAnnotationNames = setOf("InternalApi", "InternalSdkApi")
+
+private fun <T> T.isInternal() where T : WithExtraProperties<out Documentable> =
+    extra[Annotations]?.directAnnotations.orEmpty().values.flatten().any { annotation ->
+        annotation.dri.classNames in internalAnnotationNames
+    }

build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/extensions/NoOpSearchbarDataInstaller.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package aws.sdk.kotlin.gradle.dokka.extensions
+
+import org.jetbrains.dokka.base.renderers.html.SearchRecord
+import org.jetbrains.dokka.base.renderers.html.SearchbarDataInstaller
+import org.jetbrains.dokka.pages.DriResolver
+import org.jetbrains.dokka.plugability.DokkaContext
+
+/**
+ * Disable the search bar data (pages.json).
+ */
+class NoOpSearchbarDataInstaller(context: DokkaContext) : SearchbarDataInstaller(context) {
+    override fun generatePagesList(pages: List<SignatureWithId>, locationResolver: DriResolver) = listOf<SearchRecord>()
+}

build-plugins/build-support/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin

@@ -0,0 +1 @@
+aws.sdk.kotlin.gradle.dokka.DokkaConventionsPlugin

gradle/libs.versions.toml

@@ -3,8 +3,11 @@ ktlint = "1.3.0"
 smithy-version = "1.42.0"
 smithy-gradle-plugin-version = "0.9.0"
 junit-version = "5.10.1"
+dokka-version = "1.9.10"
 
 [libraries]
+dokka-core = { module = "org.jetbrains.dokka:dokka-core", version.ref = "dokka-version" }
+dokka-base = { module = "org.jetbrains.dokka:dokka-base", version.ref = "dokka-version" }
 ktlint-cli = { module = "com.pinterest.ktlint:ktlint-cli", version.ref = "ktlint" }
 ktlint-rule-engine-core = { module = "com.pinterest.ktlint:ktlint-rule-engine-core", version.ref = "ktlint" }
 ktlint-cli-ruleset-core = { module = "com.pinterest.ktlint:ktlint-cli-ruleset-core", version.ref = "ktlint" }
@@ -16,4 +19,4 @@ smithy-gradle-base-plugin = { module = "software.amazon.smithy:smithy-base-plugi
 junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit-version" }
 
 [plugins]
-plugin-publish = { id = "com.gradle.plugin-publish", version = "1.2.1"}
+plugin-publish = { id = "com.gradle.plugin-publish", version = "1.2.1"}