fix: enable intra-repo links in API ref docs (#716)

Author: ianbotsf

.changes/5131b50a-6b6c-448e-8fac-c8b5a74b01aa.json

@@ -0,0 +1,8 @@
+{
+    "id": "5131b50a-6b6c-448e-8fac-c8b5a74b01aa",
+    "type": "bugfix",
+    "description": "Enable intra-repo links in API ref docs",
+    "issues": [
+        "awslabs/aws-sdk-kotlin#715"
+    ]
+}

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

@@ -165,7 +165,12 @@ tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompileCommon> {
 }
 
 tasks.withType<org.gradle.jvm.tasks.Jar> {
-    dependsOn(codegenTask)
+    if (name == "jar" || name == "javadocJar") {
+        println("Disabling $project task '$name' because it conflicts with Kotlin JAR tasks")
+        enabled = false
+    } else {
+        dependsOn(codegenTask)
+    }
 }
 
 codegen.projections.all {
@@ -196,4 +201,4 @@ tasks.named<DokkaTaskPartial>("dokkaHtmlPartial") {
             suppress.set(true)
         }
     }
-}
+}

build.gradle.kts

@@ -55,13 +55,19 @@ subprojects {
 
         val smithyKotlinPackageListUrl: String? by project
         val smithyKotlinDocBaseUrl: String? by project
+        val smithyKotlinVersion: 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
-        if (!smithyKotlinDocBaseUrl.isNullOrEmpty() && !smithyKotlinPackageListUrl.isNullOrEmpty()) {
+        smithyKotlinDocBaseUrl.takeUnless { it.isNullOrEmpty() }?.let { docBaseUrl ->
+            val expandedDocBaseUrl = docBaseUrl.replace("\$smithyKotlinVersion", smithyKotlinVersion)
             dokkaSourceSets.configureEach {
                 externalDocumentationLink {
-                    packageListUrl.set(URL(smithyKotlinPackageListUrl))
-                    url.set(URL(smithyKotlinDocBaseUrl))
+                    url.set(URL(expandedDocBaseUrl))
+
+                    smithyKotlinPackageListUrl
+                        .takeUnless { it.isNullOrEmpty() }
+                        ?.let { packageListUrl.set(URL(it)) }
                 }
             }
         }
@@ -99,6 +105,12 @@ project.afterEvaluate {
     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.get().resolve(child.project.name) }
+
         includes.from(
             // NOTE: these get concatenated
             rootProject.file("docs/dokka-presets/README.md"),

gradle.properties

@@ -1,6 +1,7 @@
 kotlin.code.style=official
 kotlin.mpp.stability.nowarn=true
 kotlin.native.ignoreDisabledTargets=true
+kotlin.mpp.enableCompatibilityMetadataVariant=true
 
 # gradle
 org.gradle.jvmargs=-Xmx6g -XX:MaxMetaspaceSize=2G
@@ -12,7 +13,7 @@ sdkVersion=0.17.8-SNAPSHOT
 smithyVersion=1.25.2
 smithyGradleVersion=0.6.0
 # smithy-kotlin codegen and runtime are versioned together
-smithyKotlinVersion=0.12.8
+smithyKotlinVersion=0.12.9-SNAPSHOT
 
 # kotlin
 kotlinVersion=1.7.10
@@ -38,5 +39,4 @@ mockkVersion=1.12.3
 slf4jVersion=1.7.36
 
 # dokka config (values specified at build-time as needed)
-smithyKotlinPackageListUrl=
-smithyKotlinDocBaseUrl=https://docs.aws.amazon.com/sdk-for-kotlin/latest/reference/smithy-kotlin
+smithyKotlinDocBaseUrl=https://sdk.amazonaws.com/kotlin/api/smithy-kotlin/api/$smithyKotlinVersion/