Trimmed navigation and external docs samples are working

Author: lauzadis

build.gradle.kts

@@ -38,69 +38,6 @@ val testJavaVersion = typedProp<String>("test.java.version")?.let {
 }
 
 allprojects {
-//    apply(from = "${rootProject.file("buildSrc/src/main/kotlin/dokka-customization.gradle.kts")}")
-//
-//    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")}",
-//                        "${rootProject.file("docs/dokka-presets/scripts/custom-navigation-loader.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)
-//    }
-//
-//    tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial>().configureEach {
-//        dokkaSourceSets.configureEach {
-//            samples.from(project.file("samples").path, project.file("generated-src/samples").path)
-//
-//            // Each module can include their own top-level module documentation in one or more included Markdown files,
-//            // each of which must begin with `# Module <module-name>` where <module-name> is the literal name of the
-//            // Gradle module. See https://kotlinlang.org/docs/dokka-module-and-package-docs.html for more details.
-//            val includeFiles = setOf(
-//                "OVERVIEW.md", // Auto-generated by ModuleDocumentationIntegration
-//                "DOCS.md", // Hand-written docs explaining a module in greater detail
-//                "API.md", // Auto-generated by `kat` tool
-//            ).mapNotNull { project.file(it).takeIf { it.exists() } }
-//            includes.from(includeFiles)
-//        }
-//
-//        val smithyKotlinPackageListUrl: String? by project
-//        val smithyKotlinDocBaseUrl: 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
-//        smithyKotlinDocBaseUrl.takeUnless { it.isNullOrEmpty() }?.let { docBaseUrl ->
-//            val expandedDocBaseUrl = docBaseUrl.replace("\$smithyKotlinRuntimeVersion", libs.versions.smithy.kotlin.runtime.version.get())
-//            dokkaSourceSets.configureEach {
-//                externalDocumentationLink {
-//                    url.set(URL(expandedDocBaseUrl))
-//
-//                    smithyKotlinPackageListUrl
-//                        .takeUnless { it.isNullOrEmpty() }
-//                        ?.let { packageListUrl.set(URL(it)) }
-//                }
-//            }
-//        }
-//    }
-
     if (rootProject.typedProp<Boolean>("kotlinWarningsAsErrors") == true) {
         tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
             compilerOptions.allWarningsAsErrors = true
@@ -133,29 +70,6 @@ dokka {
     }
 }
 
-
-//project.afterEvaluate {
-//    // configure the root multimodule docs
-//    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.dir(child.moduleName)
-//        }
-//
-//        includes.from(
-//            // NOTE: these get concatenated
-//            rootProject.file("docs/dokka-presets/README.md"),
-//        )
-//
-//        finalizedBy("trimNavigations", "applyCustomNavigationLoader")
-//    }
-//}
-
 // Aggregate subprojects' documentation
 dependencies {
     dokka(project(":aws-runtime"))

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

@@ -1,4 +1,10 @@
-import kotlin.text.set
+import org.jsoup.Jsoup
+import kotlin.io.path.ExperimentalPathApi
+import kotlin.io.path.PathWalkOption
+import kotlin.io.path.exists
+import kotlin.io.path.isDirectory
+import kotlin.io.path.name
+import kotlin.io.path.walk
 
 plugins {
     id("org.jetbrains.dokka")
@@ -20,6 +26,7 @@ dokka {
         customAssets.from(
             rootProject.file("docs/dokka-presets/assets/logo-icon.svg"),
             rootProject.file("docs/dokka-presets/scripts/accessibility.js"),
+            rootProject.file("docs/dokka-presets/scripts/custom-navigation-loader.js"),
         )
 
         templatesDir.set(rootProject.file("docs/dokka-presets/templates"))
@@ -42,6 +49,16 @@ dokka {
         if (name == "commonMain") {
             samples.from(project.file("samples").path, project.file("generated-src/samples").path)
         }
+
+        // Each module can include their own top-level module documentation in one or more included Markdown files,
+        // each of which must begin with `# Module <module-name>` where <module-name> is the literal name of the
+        // Gradle module. See https://kotlinlang.org/docs/dokka-module-and-package-docs.html for more details.
+        val includeFiles = setOf(
+            "OVERVIEW.md", // Auto-generated by ModuleDocumentationIntegration
+            "DOCS.md", // Hand-written docs explaining a module in greater detail
+            "API.md", // Auto-generated by `kat` tool
+        ).mapNotNull { project.file(it).takeIf { it.exists() } }
+        includes.from(includeFiles)
     }
 
     // Configure Dokka to link to smithy-kotlin types
@@ -58,3 +75,41 @@ dokka {
 dependencies {
     dokkaPlugin(project(":dokka-aws"))
 }
+
+tasks.register("trimNavigations") {
+    description = "Trims navigation.html files to remove unrelated projects' side menus"
+    group = "documentation"
+
+    doLast {
+        val dokkaOutputDir = layout.buildDirectory.get().dir("dokka/html").asFile.toPath()
+
+        if (!dokkaOutputDir.exists()) {
+            logger.info("Dokka output directory not found at ${dokkaOutputDir.toAbsolutePath()}, skipping navigation trimming")
+            return@doLast
+        }
+
+        @OptIn(ExperimentalPathApi::class)
+        dokkaOutputDir.walk(PathWalkOption.INCLUDE_DIRECTORIES)
+            .filter { it.isDirectory() && it.resolve("navigation.html").exists() }
+            .forEach { moduleDir ->
+                val moduleName = moduleDir.name
+
+                val navigation = moduleDir.resolve("navigation.html").toFile()
+                val doc = Jsoup.parse(navigation)
+
+                // Trim side menus
+                doc.select("div.sideMenu > div.toc--part")
+                    .filterNot { it.id().startsWith("$moduleName-nav-submenu") }
+                    .forEach { it.remove() }
+
+                // Update navigation.html
+                val trimmedSideMenuParts = doc.select("div.sideMenu > div.toc--part")
+                navigation.writeText("<div class=\"sideMenu\">\n$trimmedSideMenuParts\n</div>")
+            }
+    }
+}
+
+tasks.dokkaGenerate {
+    finalizedBy("trimNavigations")
+}
+