Skip to content

Commit c4be558

Browse files
lauzadislauzadis
authored
misc: upgrade to Dokka 2.0.0 (#1597)
1 parent a9c1922 commit c4be558

File tree

32 files changed

+670
-570
lines changed

32 files changed

+670
-570
lines changed

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"id": "fb53db86-ba89-44ae-86e3-1c85abb9c217",
3+
"type": "misc",
4+
"description": "Upgrade to Dokka 2.0.0"
5+
}

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
import aws.sdk.kotlin.gradle.codegen.dsl.generateSmithyProjections
66
import aws.sdk.kotlin.gradle.codegen.dsl.smithyKotlinPlugin
77
import aws.sdk.kotlin.gradle.codegen.smithyKotlinProjectionSrcDir
8-
import org.jetbrains.dokka.gradle.DokkaTaskPartial
98

109
plugins {
1110
alias(libs.plugins.aws.kotlin.repo.tools.smithybuild)
@@ -85,7 +84,6 @@ smithyBuild {
8584
val basePackage = "aws.sdk.kotlin.runtime.auth.credentials.internal"
8685

8786
projections {
88-
8987
// generate an sts client
9088
create("sts-credentials-provider") {
9189
imports = listOf(
@@ -243,9 +241,12 @@ smithyBuild.projections.all {
243241
}
244242
}
245243

246-
// suppress internal generated clients
247-
tasks.named<DokkaTaskPartial>("dokkaHtmlPartial") {
248-
dependsOn(tasks.generateSmithyProjections)
244+
// Suppress internally-generated clients
245+
dokka {
246+
tasks.dokkaGenerateModuleHtml {
247+
dependsOn(tasks.generateSmithyProjections)
248+
}
249+
249250
dokkaSourceSets.configureEach {
250251
perPackageOption {
251252
matchingRegex.set(""".*\.internal.*""")

‎aws-runtime/build.gradle.kts‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
99
description = "AWS client runtime support for generated service clients"
1010

1111
plugins {
12-
alias(libs.plugins.dokka)
12+
`dokka-convention`
1313
alias(libs.plugins.kotlinx.binary.compatibility.validator)
1414
alias(libs.plugins.aws.kotlin.repo.tools.kmp) apply false
1515
jacoco
@@ -28,7 +28,6 @@ subprojects {
2828

2929
apply {
3030
plugin("org.jetbrains.kotlin.multiplatform")
31-
plugin("org.jetbrains.dokka")
3231
plugin(libraries.plugins.aws.kotlin.repo.tools.kmp.get().pluginId)
3332
}
3433

@@ -61,10 +60,6 @@ subprojects {
6160
listOf("kotlin.RequiresOptIn").forEach { languageSettings.optIn(it) }
6261
}
6362

64-
dependencies {
65-
dokkaPlugin(project(":dokka-aws"))
66-
}
67-
6863
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
6964
compilerOptions {
7065
jvmTarget.set(JvmTarget.JVM_1_8)
@@ -77,3 +72,11 @@ subprojects {
7772
}
7873
}
7974
}
75+
76+
// Configure Dokka for subprojects
77+
dependencies {
78+
subprojects.forEach {
79+
it.plugins.apply("dokka-convention") // Apply the Dokka conventions plugin to the subproject
80+
dokka(project(it.path)) // Aggregate the subprojects' generated documentation
81+
}
82+
}

‎build.gradle.kts‎

Lines changed: 16 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
import aws.sdk.kotlin.gradle.dsl.configureLinting
66
import aws.sdk.kotlin.gradle.dsl.configureNexus
77
import aws.sdk.kotlin.gradle.util.typedProp
8-
import java.net.URL
98

109
buildscript {
1110
// NOTE: buildscript classpath for the root project is the parent classloader for the subprojects, we
@@ -18,10 +17,10 @@ buildscript {
1817
}
1918

2019
plugins {
21-
alias(libs.plugins.dokka)
20+
`dokka-convention`
2221
// ensure the correct version of KGP ends up on our buildscript classpath
23-
alias(libs.plugins.kotlin.multiplatform) apply false
24-
alias(libs.plugins.kotlin.jvm) apply false
22+
id(libs.plugins.kotlin.multiplatform.get().pluginId) apply false
23+
id(libs.plugins.kotlin.jvm.get().pluginId) apply false
2524
alias(libs.plugins.aws.kotlin.repo.tools.artifactsizemetrics)
2625
}
2726

@@ -39,72 +38,9 @@ val testJavaVersion = typedProp<String>("test.java.version")?.let {
3938
}
4039

4140
allprojects {
42-
apply(from = "${rootProject.file("buildSrc/src/main/kotlin/dokka-customization.gradle.kts")}")
43-
44-
tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaTask>().configureEach {
45-
val sdkVersion: String by project
46-
moduleVersion.set(sdkVersion)
47-
48-
val year = java.time.LocalDate.now().year
49-
val pluginConfigMap = mapOf(
50-
"org.jetbrains.dokka.base.DokkaBase" to """
51-
{
52-
"customStyleSheets": [
53-
"${rootProject.file("docs/dokka-presets/css/logo-styles.css")}",
54-
"${rootProject.file("docs/dokka-presets/css/aws-styles.css")}"
55-
],
56-
"customAssets": [
57-
"${rootProject.file("docs/dokka-presets/assets/logo-icon.svg")}",
58-
"${rootProject.file("docs/dokka-presets/assets/aws_logo_white_59x35.png")}",
59-
"${rootProject.file("docs/dokka-presets/scripts/accessibility.js")}",
60-
"${rootProject.file("docs/dokka-presets/scripts/custom-navigation-loader.js")}"
61-
],
62-
"footerMessage": "© $year, Amazon Web Services, Inc. or its affiliates. All rights reserved.",
63-
"separateInheritedMembers" : true,
64-
"templatesDir": "${rootProject.file("docs/dokka-presets/templates")}"
65-
}
66-
""",
67-
)
68-
pluginsMapConfiguration.set(pluginConfigMap)
69-
}
70-
71-
tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial>().configureEach {
72-
dokkaSourceSets.configureEach {
73-
samples.from(project.file("samples").path, project.file("generated-src/samples").path)
74-
75-
// Each module can include their own top-level module documentation in one or more included Markdown files,
76-
// each of which must begin with `# Module <module-name>` where <module-name> is the literal name of the
77-
// Gradle module. See https://kotlinlang.org/docs/dokka-module-and-package-docs.html for more details.
78-
val includeFiles = setOf(
79-
"OVERVIEW.md", // Auto-generated by ModuleDocumentationIntegration
80-
"DOCS.md", // Hand-written docs explaining a module in greater detail
81-
"API.md", // Auto-generated by `kat` tool
82-
).mapNotNull { project.file(it).takeIf { it.exists() } }
83-
includes.from(includeFiles)
84-
}
85-
86-
val smithyKotlinPackageListUrl: String? by project
87-
val smithyKotlinDocBaseUrl: String? by project
88-
89-
// Configure Dokka to link to smithy-kotlin types if specified in properties
90-
// These optional properties are supplied api the api docs build job but are unneeded otherwise
91-
smithyKotlinDocBaseUrl.takeUnless { it.isNullOrEmpty() }?.let { docBaseUrl ->
92-
val expandedDocBaseUrl = docBaseUrl.replace("\$smithyKotlinRuntimeVersion", libs.versions.smithy.kotlin.runtime.version.get())
93-
dokkaSourceSets.configureEach {
94-
externalDocumentationLink {
95-
url.set(URL(expandedDocBaseUrl))
96-
97-
smithyKotlinPackageListUrl
98-
.takeUnless { it.isNullOrEmpty() }
99-
?.let { packageListUrl.set(URL(it)) }
100-
}
101-
}
102-
}
103-
}
104-
10541
if (rootProject.typedProp<Boolean>("kotlinWarningsAsErrors") == true) {
10642
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
107-
kotlinOptions.allWarningsAsErrors = true
43+
compilerOptions.allWarningsAsErrors = true
10844
}
10945
}
11046

@@ -123,28 +59,24 @@ allprojects {
12359
tasks.register<DependencyReportTask>("allDeps") { }
12460
}
12561

126-
project.afterEvaluate {
127-
// configure the root multimodule docs
128-
tasks.dokkaHtmlMultiModule.configure {
129-
moduleName.set("AWS SDK for Kotlin")
130-
131-
// Output subprojects' docs to <docs-base>/project-name/* instead of <docs-base>/path/to/project-name/*
132-
// This is especially important for inter-repo linking (e.g., via externalDocumentationLink) because the
133-
// package-list doesn't contain enough project path information to indicate where modules' documentation are
134-
// located.
135-
fileLayout.set { parent, child ->
136-
parent.outputDirectory.dir(child.moduleName)
137-
}
62+
// Configure root module's documentation
63+
dokka {
64+
moduleName.set("AWS SDK for Kotlin")
13865

66+
dokkaPublications.html {
13967
includes.from(
140-
// NOTE: these get concatenated
14168
rootProject.file("docs/dokka-presets/README.md"),
14269
)
143-
144-
finalizedBy("trimNavigations", "applyCustomNavigationLoader")
14570
}
14671
}
14772

73+
// Aggregate subprojects' documentation
74+
dependencies {
75+
dokka(project(":aws-runtime"))
76+
dokka(project(":services"))
77+
dokka(project(":hll"))
78+
}
79+
14880
// Publishing
14981
configureNexus()
15082

@@ -155,6 +87,7 @@ val lintPaths = listOf(
15587
"!**/generated/ksp/**",
15688
"!**/kspCaches/**",
15789
"!**/smithyprojections/**",
90+
"!**/build/**",
15891
)
15992

16093
configureLinting(lintPaths)

‎buildSrc/build.gradle.kts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11
plugins {
22
alias(libs.plugins.kotlin.jvm)
3+
`kotlin-dsl`
34
}
45

56
repositories {
67
mavenCentral()
8+
gradlePluginPortal()
9+
}
10+
11+
dependencies {
12+
implementation(libs.dokka.gradle.plugin)
13+
implementation(libs.kotlin.gradle.plugin)
714
}
815

916
dependencies {

‎buildSrc/settings.gradle.kts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
rootProject.name = "buildSrc"
2+
13
dependencyResolutionManagement {
24
versionCatalogs {
35
create("libs") {

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

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
import org.jsoup.Jsoup
2+
import kotlin.io.path.ExperimentalPathApi
3+
import kotlin.io.path.PathWalkOption
4+
import kotlin.io.path.exists
5+
import kotlin.io.path.isDirectory
6+
import kotlin.io.path.name
7+
import kotlin.io.path.walk
8+
9+
plugins {
10+
id("org.jetbrains.dokka")
11+
}
12+
13+
dokka {
14+
val sdkVersion: String by project
15+
moduleVersion.set(sdkVersion)
16+
17+
dokkaGeneratorIsolation = ProcessIsolation {
18+
maxHeapSize = "4g"
19+
}
20+
21+
pluginsConfiguration.html {
22+
customStyleSheets.from(
23+
rootProject.file("docs/dokka-presets/css/aws-styles.css"),
24+
)
25+
26+
customAssets.from(
27+
rootProject.file("docs/dokka-presets/assets/logo-icon.svg"),
28+
rootProject.file("docs/dokka-presets/scripts/accessibility.js"),
29+
rootProject.file("docs/dokka-presets/scripts/custom-navigation-loader.js"),
30+
)
31+
32+
templatesDir.set(rootProject.file("docs/dokka-presets/templates"))
33+
34+
footerMessage.set("© ${java.time.LocalDate.now().year}, Amazon Web Services, Inc. or its affiliates. All rights reserved.")
35+
separateInheritedMembers.set(true)
36+
}
37+
38+
// each module can include their own top-level module documentation
39+
// see https://kotlinlang.org/docs/kotlin-doc.html#module-and-package-documentation
40+
if (project.file("API.md").exists()) {
41+
dokkaSourceSets.configureEach {
42+
includes.from(project.file("API.md"))
43+
}
44+
}
45+
46+
dokkaSourceSets.configureEach {
47+
// Only configure samples on `commonMain`.
48+
// Fixes compiler warnings: "Source sets 'common' and 'desktop' have the common sample roots. In Dokka K2 it will be an error."
49+
if (name == "commonMain") {
50+
samples.from(project.file("samples").path, project.file("generated-src/samples").path)
51+
}
52+
53+
// Each module can include their own top-level module documentation in one or more included Markdown files,
54+
// each of which must begin with `# Module <module-name>` where <module-name> is the literal name of the
55+
// Gradle module. See https://kotlinlang.org/docs/dokka-module-and-package-docs.html for more details.
56+
val includeFiles = setOf(
57+
"OVERVIEW.md", // Auto-generated by ModuleDocumentationIntegration
58+
"DOCS.md", // Hand-written docs explaining a module in greater detail
59+
"API.md", // Auto-generated by `kat` tool
60+
).mapNotNull { project.file(it).takeIf { it.exists() } }
61+
includes.from(includeFiles)
62+
}
63+
64+
// Configure Dokka to link to smithy-kotlin types
65+
dokkaSourceSets.configureEach {
66+
externalDocumentationLinks {
67+
create("smithy-kotlin") {
68+
val smithyKotlinRuntimeVersion = versionCatalogs.named("libs").findVersion("smithy-kotlin-runtime-version").get()
69+
url("https://sdk.amazonaws.com/kotlin/api/smithy-kotlin/api/$smithyKotlinRuntimeVersion")
70+
}
71+
}
72+
}
73+
}
74+
75+
dependencies {
76+
dokkaPlugin(project(":dokka-aws"))
77+
}
78+
79+
tasks.register("trimNavigationFiles") {
80+
description = "Trims navigation.html files to remove unrelated projects' side menus"
81+
group = "documentation"
82+
83+
doLast {
84+
val dokkaOutputDir = layout.buildDirectory.get().dir("dokka/html").asFile.toPath()
85+
86+
if (!dokkaOutputDir.exists()) {
87+
logger.info("Dokka output directory not found at ${dokkaOutputDir.toAbsolutePath()}, skipping navigation trimming")
88+
return@doLast
89+
}
90+
91+
@OptIn(ExperimentalPathApi::class)
92+
dokkaOutputDir.walk(PathWalkOption.INCLUDE_DIRECTORIES)
93+
.filter { it.isDirectory() && it.resolve("navigation.html").exists() }
94+
.forEach { moduleDir ->
95+
val moduleName = moduleDir.name
96+
97+
val navigation = moduleDir.resolve("navigation.html").toFile()
98+
val doc = Jsoup.parse(navigation)
99+
100+
// Fix navigation links
101+
doc.select("a[href^='../../../../']").forEach { anchor ->
102+
val originalHref = anchor.attr("href")
103+
val trimmedHref = originalHref.replace("../../../../", "")
104+
anchor.attr("href", trimmedHref)
105+
}
106+
107+
// Trim side menus
108+
doc.select("div.sideMenu > div.toc--part")
109+
.filterNot { it.id().startsWith("$moduleName-nav-submenu") }
110+
.forEach { moduleMenu ->
111+
val moduleRow = moduleMenu.select("div.toc--row").first()!!
112+
val toggleButton = moduleRow.select("button.toc--button").single()
113+
toggleButton.remove()
114+
115+
moduleMenu.children()
116+
.filterNot { it == moduleRow }
117+
.forEach { it.remove() }
118+
}
119+
120+
// Update navigation.html
121+
val trimmedSideMenuParts = doc.select("div.sideMenu > div.toc--part")
122+
navigation.writeText("<div class=\"sideMenu\">\n$trimmedSideMenuParts\n</div>")
123+
}
124+
}
125+
}
126+
127+
tasks.dokkaGenerate {
128+
finalizedBy("trimNavigationFiles")
129+
}

0 commit comments

Comments
 (0)