Dokka Gradle plugin doc update

docs/dokka.tree

@@ -1,11 +1,12 @@
 <?xml version='1.0' encoding='utf-8'?>
 <!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
-<instance-profile id="dokka" name="dokka" start-page="dokka-introduction.md">
+<instance-profile id="dokka" name="dokka" start-page="dokka-gradle-troubleshooting-md.md">
 	<snippet id="dokka">
 		<toc-element topic="dokka-introduction.md"/>
 		<toc-element topic="dokka-get-started.md"/>
 		<toc-element toc-title="Run Dokka">
 			<toc-element topic="dokka-gradle.md"/>
+			<toc-element topic="dokka-gradle-troubleshooting-md.md"/>
 			<toc-element topic="dokka-migration.md"/>
 			<toc-element topic="dokka-maven.md"/>
 			<toc-element topic="dokka-cli.md"/>

docs/labels.list

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  - Copyright 2014-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+  -->
+
+<!DOCTYPE labels SYSTEM "https://resources.jetbrains.com/writerside/1.0/labels-list.dtd">
+<labels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/labels.xsd">
+
+    <primary-label id="experimental-general" name="Experimental" short-name="Experimental" href="components-stability.html#stability-levels-explained" color="red">The feature is Experimental. It may be dropped or changed at any time. Use it only for evaluation purposes.</primary-label>
+    <primary-label id="experimental-opt-in" name="Experimental" short-name="Experimental" href="components-stability.html#stability-levels-explained" color="red" >The feature is Experimental. It may be dropped or changed at any time. Opt-in is required (see the details below), and you should use it only for evaluation purposes.</primary-label>
+    <primary-label id="alpha" name="Alpha" short-name="α" href="components-stability.html#stability-levels-explained" color="strawberry">The feature is in Alpha. It may change incompatibly and require manual migration in the future.</primary-label>
+    <primary-label id="beta" name="Beta" short-name="β" href="components-stability.html#stability-levels-explained" color="tangerine">The feature is in Beta. It is almost stable, but migration steps may be required in the future. We'll do our best to minimize any changes you have to make.</primary-label>
+    <primary-label id="advanced" name="Advanced" short-name="☆" color="purple"></primary-label>
+    <primary-label id="eap" name="EAP" short-name="EAP" color="red">This functionality is available only in the latest EAP version.</primary-label>
+
+    <secondary-label id="eap" name="EAP" color="red">This functionality is available only in the latest EAP version.</secondary-label>
+</labels>

docs/topics/dokka-get-started.md

@@ -5,40 +5,49 @@ Below you can find simple instructions to help you get started with Dokka.
 <tabs group="build-script">
 <tab title="Gradle Kotlin DSL" group-key="kotlin">
 
-> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, several configuration options, Gradle tasks, and steps to generate your documentation have been updated, including:
->
-> * [Adjust configuration options](dokka-migration.md#adjust-configuration-options)
-> * [Work with multi-module projects](dokka-migration.md#share-dokka-configuration-across-modules)
-> * [Generate documentation with the updated tasks](dokka-migration.md#generate-documentation-with-the-updated-task)
-> * [Specify an output directory](dokka-migration.md#output-directory)
->
-> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md).
+> This guide applies to Dokka Gradle Plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. 
+> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md).
 >
 {style="note"}
 
-Apply the Gradle plugin for Dokka in the root build script of your project:
+**Apply the Gradle Dokka plugin** 
+
+Apply the Dokka Gradle plugin (DGP) in the root build script of your project:
 
 ```kotlin
 plugins {
     id("org.jetbrains.dokka") version "%dokkaVersion%"
 }
 ```
 
-When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need 
-to apply the Gradle plugin within subprojects as well:
+**Document multi-project builds**
 
-```kotlin
-subprojects {
-    apply(plugin = "org.jetbrains.dokka")
-}
+When documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html),
+you need to apply the plugin to every subproject you want to document. Share Dokka configuration across subprojects 
+by using one of the following approaches:
+
+* Convention plugin
+* Direct configuration in each subproject if you’re not using convention plugins
+
+For more information about sharing Dokka configuration in multi-project builds, 
+see [Multi-project configuration](dokka-gradle.md#multi-project-configuration).
+
+**Generate documentation**
+
+To generate documentation, run the following Gradle task:
+
+```Bash
+./gradlew :dokkaGenerate
 ```
 
-To generate documentation, run the following Gradle tasks:
+This task works for both single and multi-project builds. 
+You can use different tasks to generate output in [HTML](dokka-html.md), 
+[Javadoc](dokka-javadoc.md) or both [HTML and Javadoc](dokka-gradle.md#configure-documentation-output-format).
 
-* `dokkaHtml` for single-project builds
-* `dokkaHtmlMultiModule` for multi-project builds
+**Set output directory** 
 
-By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
+By default, the output directory is set to `/build/dokka/html` for both multi-project and single-project builds, 
+but you can [configure it](dokka-gradle.md#general-configuration).
 
 To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
 
@@ -69,7 +78,9 @@ To generate documentation, run the following Gradle tasks:
 
 By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
 
-To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
+> To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
+>
+{style="tip"}
 
 </tab>
 <tab title="Maven" group-key="mvn">

docs/topics/dokka-gradle-troubleshooting-md.md

@@ -0,0 +1,71 @@
+[//]: # (title: Dokka Gradle 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 is 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"}