Merge branch 'master' into dependson

.gitattributes

@@ -42,6 +42,8 @@ docs-developer/**                                                   linguist-doc
 examples/**                                                         linguist-documentation
 dokka-integration-tests/gradle/projects/**                          linguist-documentation
 
+# exclude test data
+dokka-integration-tests/gradle/projects/**/expectedData/**                                linguist-generated
 dokka-integration-tests/gradle/src/testExampleProjects/expectedData/**                    linguist-generated
 dokka-runners/dokka-gradle-plugin/src/testFunctional/resources/KotlinDslAccessorsTest/**  linguist-generated
 

build.gradle.kts

@@ -115,12 +115,15 @@ idea {
                 ".idea",
                 ".husky",
                 ".kotlin",
+                "dokka-integration-tests/.kotlin",
                 "dokka-runners/dokka-gradle-plugin/.kotlin",
                 "dokka-runners/runner-cli/.kotlin",
                 "dokka-runners/runner-maven-plugin/.kotlin",
                 "dokka-runners/dokka-gradle-plugin/src/testFunctional/resources/KotlinDslAccessorsTest/",
 
                 "dokka-integration-tests/gradle/src/testExampleProjects/expectedData",
+                "dokka-integration-tests/gradle/projects/it-android/expectedData",
+                "dokka-integration-tests/gradle/projects/it-android-compose/expectedData",
             )
         )
     }

docs/topics/dokka-migration.md

@@ -438,8 +438,75 @@ DGP v2 now supports Gradle build cache and configuration cache, improving build
 * To enable build cache, follow instructions in the [Gradle build cache documentation](https://docs.gradle.org/current/userguide/build_cache.html#sec:build_cache_enable).
 * To enable configuration cache, follow instructions in the [Gradle configuration cache documentation](https://docs.gradle.org/current/userguide/configuration_cache.html#config_cache:usage:enable ).
 
+## Troubleshooting
+
+In large projects, Dokka can consume a significant amount of memory to generate documentation.
+This can exceed Gradle’s memory limits, especially when processing large volumes of data.
+
+When Dokka generation runs out of memory, the build fails, and Gradle can throw exceptions like `java.lang.OutOfMemoryError: Metaspace`.
+
+Active efforts are underway to improve Dokka's performance, although some limitations stem from Gradle.
+
+If you encounter memory issues, try these workarounds:
+
+* [Increasing heap space](#increase-heap-space)
+* [Running Dokka within the Gradle process](#run-dokka-within-the-gradle-process)
+
+### Increase heap space
+
+One way to resolve memory issues is to increase the amount of Java heap memory for the Dokka generator process. 
+In the `build.gradle.kts` file, adjust the 
+following configuration option:
+
+```kotlin
+dokka {
+    // Dokka generates a new process managed by Gradle
+    dokkaGeneratorIsolation = ProcessIsolation {
+        // Configures heap size
+        maxHeapSize = "4g"
+    }
+}
+```
+
+In this example, the maximum heap size is set to 4 GB (`"4g"`). Adjust and test the value to find the optimal setting for your build.
+
+If you find that Dokka requires a considerably expanded heap size, for example, significantly higher than Gradle's own memory usage, 
+[create an issue on Dokka's GitHub repository](https://kotl.in/dokka-issues).
+
+> You have to apply this configuration to each subproject. It's recommended that you configure Dokka in a convention 
+> plugin applied to all subprojects.
+>
+{style="note"}
+
+### Run Dokka within the Gradle process
+
+When both the Gradle build and Dokka generation require a lot of memory, they may run as separate processes, 
+consuming significant memory on a single machine.
+
+To optimize memory usage, you can run Dokka within the same Gradle process instead of as a separate process. This 
+allows you to configure the memory for Gradle once instead of allocating it separately for each process.
+
+To run Dokka within the same Gradle process, adjust the following configuration option in the `build.gradle.kts` file:
+
+```kotlin
+dokka {
+    // Runs Dokka in the current Gradle process
+    dokkaGeneratorIsolation = ClassLoaderIsolation()
+}
+```
+
+As with [increasing heap space](#increase-heap-space), test this configuration to confirm it works well for your project.
+
+For more details on configuring Gradle's JVM memory, see the [Gradle documentation](https://docs.gradle.org/current/userguide/config_gradle.html#sec:configuring_jvm_memory).
+
+> Changing the Java options for Gradle launches a new Gradle daemon, which may stay alive for a long time. You can [manually stop any other Gradle processes](https://docs.gradle.org/current/userguide/gradle_daemon.html#sec:stopping_an_existing_daemon).
+> 
+> Additionally, Gradle issues with the `ClassLoaderIsolation()` configuration may [cause memory leaks](https://github.com/gradle/gradle/issues/18313). 
+>
+{style="note"}
+
 ## What's next
 
 * Explore more [DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2). 
 * [Get started with Dokka](dokka-get-started.md).
-* [Learn more about Dokka plugins](dokka-plugins.md).
+* [Learn more about Dokka plugins](dokka-plugins.md).

dokka-integration-tests/gradle/build.gradle.kts

@@ -25,7 +25,7 @@ dependencies {
     api(libs.kotlin.test)
     api(libs.junit.jupiterApi)
     api(libs.junit.jupiterParams)
-
+    api(libs.kotest.assertionsCore)
     api(gradleTestKit())
 
     api(testFixtures("org.jetbrains.dokka:dokka-gradle-plugin:$dokkaVersion"))
@@ -176,6 +176,32 @@ fun registerTestProjectSuite(
     }
 }
 
+testing.suites.named<JvmTestSuite>("test") {
+    targets.configureEach {
+        testTask {
+            systemProperty
+                .inputDirectory("templateProjectsDir", templateProjectsDir)
+                .withPathSensitivity(RELATIVE)
+
+            // Don't register ANDROID_HOME as a Task input, because the path is different on everyone's machine,
+            // which means Gradle will never be able to cache the task.
+            dokkaBuild.androidSdkDir.orNull?.let { androidSdkDir ->
+                environment("ANDROID_HOME", androidSdkDir)
+            }
+
+            // Use a stable Java version for running Gradle in integration tests.
+            // There's no need to parameterise the version, to re-run the tests with different JDKs.
+            // There are a few reasons for this:
+            // - Some tests use AGP 8, which requires Gradle 17+.
+            // - DGP functional tests are already run with Java 8, so we don't need to re-test Java 8 compatibility here.
+            // - The JDK used to run Gradle doesn't affect the Dokka output. The Java Toolchain used to compile
+            //   the code in test projects does affect the output... but that can be parameterised in the
+            //   individual tests if necessary.
+            javaLauncher = javaToolchains.launcherFor { languageVersion = JavaLanguageVersion.of(17) }
+        }
+    }
+}
+
 val checkoutKotlinxCoroutines by tasks.registering(GitCheckoutTask::class) {
     uri = "https://github.com/Kotlin/kotlinx.coroutines.git"
     commitId = "b78bbf518bd8e90e9ed2133ebdacc36441210cd6"
@@ -193,6 +219,9 @@ testing {
         targets.configureEach {
             testTask.configure {
                 devMavenPublish.configureTask(this)
+
+                // temp workaround, remove when all `testTemplateProject*` source sets are removed
+                mustRunAfter(tasks.withType<GitCheckoutTask>())
             }
         }
     }

dokka-integration-tests/gradle/projects/it-android-compose/build.gradle.kts

@@ -0,0 +1,16 @@
+plugins {
+    alias(libs.plugins.android.library) apply false
+    alias(libs.plugins.kotlin.multiplatform) apply false
+
+    if ("/* %{KGP_VERSION} */".startsWith("2.")) {
+        id("org.jetbrains.kotlin.plugin.compose") version "/* %{KGP_VERSION} */" apply false
+    }
+    alias(libs.plugins.compose.multiplatform) apply false
+
+    id("org.jetbrains.dokka") version "/* %{DGP_VERSION} */"
+}
+
+dependencies {
+    dokka(project(":core"))
+    dokka(project(":material3"))
+}

dokka-integration-tests/gradle/projects/it-android-compose/core/build.gradle.kts

@@ -0,0 +1,45 @@
+plugins {
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.multiplatform)
+    id("org.jetbrains.dokka")
+
+    if ("/* %{KGP_VERSION} */".startsWith("2.")) {
+        id("org.jetbrains.kotlin.plugin.compose")
+    }
+    alias(libs.plugins.compose.multiplatform)
+}
+
+group = "org.dokka.it.android.kmp"
+version = "1.0"
+
+android {
+    namespace = "org.dokka.it.android.kmp"
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+}
+
+kotlin {
+    jvmToolchain(17)
+
+    androidTarget {
+        publishLibraryVariants("release")
+    }
+
+    sourceSets {
+        commonMain {
+            dependencies {
+                implementation(compose.runtime)
+                implementation(compose.foundation)
+                implementation(compose.animation)
+            }
+        }
+    }
+}

dokka-integration-tests/gradle/projects/it-android-compose/core/src/androidMain/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest />

dokka-integration-tests/gradle/projects/it-android-compose/core/src/commonMain/kotlin/MenuItem.kt

@@ -0,0 +1,12 @@
+package org.dokka.it.android.kmp.core
+
+import androidx.compose.runtime.Stable
+import androidx.compose.ui.graphics.vector.ImageVector
+
+@Stable
+public data class MenuItem(
+    val label: String,
+    val imageVector: ImageVector,
+    val onClick: () -> Unit,
+    val isImportant: Boolean,
+)