Skip to content

Commit c4520f9

Browse files
AlejandraPedrozaAlejandraPedroza
committed
Dokka Gradle plugin doc update
This PR updates all the documents relevant to Dokka Gradle plugin v2 # Conflicts: # docs/topics/dokka-get-started.md # docs/topics/dokka-plugins.md # docs/topics/formats/dokka-html.md # docs/topics/formats/dokka-markdown.md
1 parent f0abfa9 commit c4520f9

File tree

10 files changed

+851
-802
lines changed

10 files changed

+851
-802
lines changed

‎docs/dokka.tree‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
<?xml version='1.0' encoding='utf-8'?>
22
<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
3-
<instance-profile id="dokka" name="dokka" start-page="dokka-introduction.md">
3+
<instance-profile id="dokka" name="dokka" start-page="dokka-gradle-troubleshooting-md.md">
44
<snippet id="dokka">
55
<toc-element topic="dokka-introduction.md"/>
66
<toc-element topic="dokka-get-started.md"/>
77
<toc-element toc-title="Run Dokka">
88
<toc-element topic="dokka-gradle.md"/>
9+
<toc-element topic="dokka-gradle-troubleshooting-md.md"/>
910
<toc-element topic="dokka-migration.md"/>
1011
<toc-element topic="dokka-maven.md"/>
1112
<toc-element topic="dokka-cli.md"/>

‎docs/labels.list‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
- Copyright 2014-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4+
-->
5+
6+
<!DOCTYPE labels SYSTEM "https://resources.jetbrains.com/writerside/1.0/labels-list.dtd">
7+
<labels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/labels.xsd">
9+
10+
<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>
11+
<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>
12+
<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>
13+
<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>
14+
<primary-label id="advanced" name="Advanced" short-name="☆" color="purple"></primary-label>
15+
<primary-label id="eap" name="EAP" short-name="EAP" color="red">This functionality is available only in the latest EAP version.</primary-label>
16+
17+
<secondary-label id="eap" name="EAP" color="red">This functionality is available only in the latest EAP version.</secondary-label>
18+
</labels>

‎docs/topics/dokka-get-started.md‎

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -5,40 +5,44 @@ Below you can find simple instructions to help you get started with Dokka.
55
<tabs group="build-script">
66
<tab title="Gradle Kotlin DSL" group-key="kotlin">
77

8-
> 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:
9-
>
10-
> * [Adjust configuration options](dokka-migration.md#adjust-configuration-options)
11-
> * [Work with multi-module projects](dokka-migration.md#share-dokka-configuration-across-modules)
12-
> * [Generate documentation with the updated tasks](dokka-migration.md#generate-documentation-with-the-updated-task)
13-
> * [Specify an output directory](dokka-migration.md#output-directory)
14-
>
15-
> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md).
16-
>
17-
{style="note"}
8+
**Apply the Gradle Dokka plugin**
189

19-
Apply the Gradle plugin for Dokka in the root build script of your project:
10+
Apply the Dokka Gradle plugin (DGP) in the root build script of your project:
2011

2112
```kotlin
2213
plugins {
2314
id("org.jetbrains.dokka") version "%dokkaVersion%"
2415
}
2516
```
2617

27-
When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need
28-
to apply the Gradle plugin within subprojects as well:
18+
**Document multi-module projects**
2919

30-
```kotlin
31-
subprojects {
32-
apply(plugin = "org.jetbrains.dokka")
33-
}
20+
When documenting [multi-module projects (multi-project builds)](https://docs.gradle.org/current/userguide/multi_project_builds.html),
21+
you don't need to apply the plugin to every module or subproject you want to document. Instead, share Dokka configuration across modules
22+
by using one of the following approaches:
23+
24+
* Convention plugin
25+
* Direct configuration in each module if you’re not using convention plugins
26+
27+
For more information about sharing Dokka configuration in multi-module projects,
28+
see [Multi-project configuration](dokka-gradle.md#multi-project-configuration).
29+
30+
**Generate documentation**
31+
32+
To generate documentation, run the following Gradle task:
33+
34+
```Bash
35+
./gradlew :dokkaGenerate
3436
```
3537

36-
To generate documentation, run the following Gradle tasks:
38+
This task works for both single and multi-module projects.
39+
You can use different tasks to generate output in [HTML](dokka-html.md),
40+
[Javadoc](dokka-javadoc.md) or both [HTML and Javadoc](dokka-gradle.md#configure-documentation-output-format).
3741

38-
* `dokkaHtml` for single-project builds
39-
* `dokkaHtmlMultiModule` for multi-project builds
42+
**Set output directory**
4043

41-
By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
44+
By default, the output directory is set to `/build/dokka/html` for both multi-module and single-module projects,
45+
but you can [configure it](dokka-gradle.md#general-configuration).
4246

4347
To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
4448

@@ -69,7 +73,9 @@ To generate documentation, run the following Gradle tasks:
6973

7074
By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.
7175

72-
To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
76+
> To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md).
77+
>
78+
{style="tip"}
7379

7480
</tab>
7581
<tab title="Maven" group-key="mvn">

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
[//]: # (title: Dokka Gradle troubleshooting)
2+
3+
In large projects, Dokka can consume a significant amount of memory to generate documentation.
4+
This can exceed Gradle’s memory limits, especially when processing large volumes of data.
5+
6+
When Dokka generation runs out of memory, the build fails,
7+
and Gradle can throw exceptions like `java.lang.OutOfMemoryError: Metaspace`.
8+
9+
Active efforts are underway to improve Dokka's performance, although some limitations stem from Gradle.
10+
11+
If you encounter memory issues, try these workarounds:
12+
13+
* [Increasing heap space](#increase-heap-space)
14+
* [Running Dokka within the Gradle process](#run-dokka-within-the-gradle-process)
15+
16+
### Increase heap space
17+
18+
One way to resolve memory issues is to increase the amount of Java heap memory for the Dokka generator process.
19+
In the `build.gradle.kts` file, adjust the
20+
following configuration option:
21+
22+
```kotlin
23+
dokka {
24+
// Dokka generates a new process managed by Gradle
25+
dokkaGeneratorIsolation = ProcessIsolation {
26+
// Configures heap size
27+
maxHeapSize = "4g"
28+
}
29+
}
30+
```
31+
32+
In this example, the maximum heap size is set to 4 GB (`"4g"`).
33+
Adjust and test the value to find the optimal setting for your build.
34+
35+
If you find that Dokka requires a considerably expanded heap size,
36+
for example, significantly higher than Gradle's own memory usage,
37+
[create an issue on Dokka's GitHub repository](https://kotl.in/dokka-issues).
38+
39+
> You have to apply this configuration to each subproject.
40+
> It is recommended that you configure Dokka in a convention
41+
> plugin applied to all subprojects.
42+
>
43+
{style="note"}
44+
45+
### Run Dokka within the Gradle process
46+
47+
When both the Gradle build and Dokka generation require a lot of memory, they may run as separate processes,
48+
consuming significant memory on a single machine.
49+
50+
To optimize memory usage, you can run Dokka within the same Gradle process instead of as a separate process.
51+
This allows you to configure the memory for Gradle once instead of allocating it separately for each process.
52+
53+
To run Dokka within the same Gradle process, adjust the following configuration option in the `build.gradle.kts` file:
54+
55+
```kotlin
56+
dokka {
57+
// Runs Dokka in the current Gradle process
58+
dokkaGeneratorIsolation = ClassLoaderIsolation()
59+
}
60+
```
61+
62+
As with [increasing heap space](#increase-heap-space), test this configuration to confirm it works well for your project.
63+
64+
For more details on configuring Gradle's JVM memory,
65+
see the [Gradle documentation](https://docs.gradle.org/current/userguide/config_gradle.html#sec:configuring_jvm_memory).
66+
67+
> 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).
68+
>
69+
> Additionally, Gradle issues with the `ClassLoaderIsolation()` configuration may [cause memory leaks](https://github.com/gradle/gradle/issues/18313).
70+
>
71+
{style="note"}

‎docs/topics/dokka-migration.md‎

Lines changed: 3 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,7 @@ The Dokka Gradle plugin (DGP) is a tool for generating comprehensive API documen
55
DGP seamlessly processes both Kotlin's KDoc comments and Java's Javadoc comments to extract information and create
66
structured documentation in [HTML or Javadoc](#select-documentation-output-format) format.
77

8-
Starting with Dokka 2.0.0, you can try the Dokka Gradle plugin v2, the new version of DGP. With Dokka 2.0.0, you can use
9-
the Dokka Gradle plugin either in v1 or v2 modes.
10-
11-
DGP v2 introduces significant improvements to DGP, aligning more closely with Gradle best practices:
8+
The Dokka Gradle plugin v2 mode is enabled by default and aligns with Gradle best practices:
129

1310
* Adopts Gradle types, which leads to better performance.
1411
* Uses an intuitive top-level DSL configuration instead of a low-level task-based setup, which simplifies the build scripts and their readability.
@@ -17,6 +14,8 @@ DGP v2 introduces significant improvements to DGP, aligning more closely with Gr
1714
* Fully supports Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html) and
1815
[build cache](https://docs.gradle.org/current/userguide/build_cache.html), which improves performance and simplifies build work.
1916

17+
Read this guide for further information between changes and migration from DGP v1 to v2 modes.
18+
2019
## Before you start
2120

2221
Before starting the migration, complete the following steps.
@@ -786,73 +785,6 @@ DGP v2 now supports Gradle build cache and configuration cache, improving build
786785
* 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).
787786
* 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 ).
788787
789-
## Troubleshooting
790-
791-
In large projects, Dokka can consume a significant amount of memory to generate documentation.
792-
This can exceed Gradle’s memory limits, especially when processing large volumes of data.
793-
794-
When Dokka generation runs out of memory, the build fails, and Gradle can throw exceptions like `java.lang.OutOfMemoryError: Metaspace`.
795-
796-
Active efforts are underway to improve Dokka's performance, although some limitations stem from Gradle.
797-
798-
If you encounter memory issues, try these workarounds:
799-
800-
* [Increasing heap space](#increase-heap-space)
801-
* [Running Dokka within the Gradle process](#run-dokka-within-the-gradle-process)
802-
803-
### Increase heap space
804-
805-
One way to resolve memory issues is to increase the amount of Java heap memory for the Dokka generator process.
806-
In the `build.gradle.kts` file, adjust the
807-
following configuration option:
808-
809-
```kotlin
810-
dokka {
811-
// Dokka generates a new process managed by Gradle
812-
dokkaGeneratorIsolation = ProcessIsolation {
813-
// Configures heap size
814-
maxHeapSize = "4g"
815-
}
816-
}
817-
```
818-
819-
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.
820-
821-
If you find that Dokka requires a considerably expanded heap size, for example, significantly higher than Gradle's own memory usage,
822-
[create an issue on Dokka's GitHub repository](https://kotl.in/dokka-issues).
823-
824-
> You have to apply this configuration to each subproject. It is recommended that you configure Dokka in a convention
825-
> plugin applied to all subprojects.
826-
>
827-
{style="note"}
828-
829-
### Run Dokka within the Gradle process
830-
831-
When both the Gradle build and Dokka generation require a lot of memory, they may run as separate processes,
832-
consuming significant memory on a single machine.
833-
834-
To optimize memory usage, you can run Dokka within the same Gradle process instead of as a separate process. This
835-
allows you to configure the memory for Gradle once instead of allocating it separately for each process.
836-
837-
To run Dokka within the same Gradle process, adjust the following configuration option in the `build.gradle.kts` file:
838-
839-
```kotlin
840-
dokka {
841-
// Runs Dokka in the current Gradle process
842-
dokkaGeneratorIsolation = ClassLoaderIsolation()
843-
}
844-
```
845-
846-
As with [increasing heap space](#increase-heap-space), test this configuration to confirm it works well for your project.
847-
848-
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).
849-
850-
> 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).
851-
>
852-
> Additionally, Gradle issues with the `ClassLoaderIsolation()` configuration may [cause memory leaks](https://github.com/gradle/gradle/issues/18313).
853-
>
854-
{style="note"}
855-
856788
## What's next
857789

858790
* [Explore more DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2).

0 commit comments

Comments
 (0)