diff --git a/build-plugins/build-support/build.gradle.kts b/build-plugins/build-support/build.gradle.kts index e76fcbf..f54b5f5 100644 --- a/build-plugins/build-support/build.gradle.kts +++ b/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 { diff --git a/build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/DokkaConventionsPlugin.kt b/build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/DokkaConventionsPlugin.kt new file mode 100644 index 0000000..49bf2a5 --- /dev/null +++ b/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() } + + 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 +} diff --git a/build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/extensions/FilterInternalApis.kt b/build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/extensions/FilterInternalApis.kt new file mode 100644 index 0000000..c0f6a93 --- /dev/null +++ b/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.isInternal() where T : WithExtraProperties = + extra[Annotations]?.directAnnotations.orEmpty().values.flatten().any { annotation -> + annotation.dri.classNames in internalAnnotationNames + } diff --git a/build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/extensions/NoOpSearchbarDataInstaller.kt b/build-plugins/build-support/src/main/kotlin/aws/sdk/kotlin/gradle/dokka/extensions/NoOpSearchbarDataInstaller.kt new file mode 100644 index 0000000..8083c62 --- /dev/null +++ b/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, locationResolver: DriResolver) = listOf() +} diff --git a/build-plugins/build-support/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/build-plugins/build-support/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin new file mode 100644 index 0000000..5b625ff --- /dev/null +++ b/build-plugins/build-support/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin @@ -0,0 +1 @@ +aws.sdk.kotlin.gradle.dokka.DokkaConventionsPlugin diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index b26f7ac..ab0cdff 100644 --- a/gradle/libs.versions.toml +++ b/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"} \ No newline at end of file +plugin-publish = { id = "com.gradle.plugin-publish", version = "1.2.1"}