diff --git a/docs/dokka.tree b/docs/dokka.tree index 49a8b4bbce..76ec6f967f 100644 --- a/docs/dokka.tree +++ b/docs/dokka.tree @@ -1,11 +1,12 @@ - + + diff --git a/docs/labels.list b/docs/labels.list new file mode 100644 index 0000000000..b8cd77c802 --- /dev/null +++ b/docs/labels.list @@ -0,0 +1,18 @@ + + + + + + + The feature is Experimental. It may be dropped or changed at any time. Use it only for evaluation purposes. + 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. + The feature is in Alpha. It may change incompatibly and require manual migration in the future. + 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. + + This functionality is available only in the latest EAP version. + + This functionality is available only in the latest EAP version. + \ No newline at end of file diff --git a/docs/topics/dokka-get-started.md b/docs/topics/dokka-get-started.md index e08eb2ba10..6edc9c29f4 100644 --- a/docs/topics/dokka-get-started.md +++ b/docs/topics/dokka-get-started.md @@ -5,18 +5,14 @@ Below you can find simple instructions to help you get started with Dokka. -> 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 { @@ -24,21 +20,34 @@ plugins { } ``` -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"} diff --git a/docs/topics/dokka-gradle-troubleshooting-md.md b/docs/topics/dokka-gradle-troubleshooting-md.md new file mode 100644 index 0000000000..64a9c489e9 --- /dev/null +++ b/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"} \ No newline at end of file diff --git a/docs/topics/dokka-migration.md b/docs/topics/dokka-migration.md index dd0f145cf0..1d23fdb3f1 100644 --- a/docs/topics/dokka-migration.md +++ b/docs/topics/dokka-migration.md @@ -5,10 +5,7 @@ The Dokka Gradle plugin (DGP) is a tool for generating comprehensive API documen DGP seamlessly processes both Kotlin's KDoc comments and Java's Javadoc comments to extract information and create structured documentation in [HTML or Javadoc](#select-documentation-output-format) format. -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 -the Dokka Gradle plugin either in v1 or v2 modes. - -DGP v2 introduces significant improvements to DGP, aligning more closely with Gradle best practices: +The Dokka Gradle plugin v2 mode is enabled by default and aligns with Gradle best practices: * Adopts Gradle types, which leads to better performance. * 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 * Fully supports Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html) and [build cache](https://docs.gradle.org/current/userguide/build_cache.html), which improves performance and simplifies build work. +Read this guide for further information between changes and migration from DGP v1 to v2 modes. + ## Before you start Before starting the migration, complete the following steps. @@ -44,7 +43,7 @@ Update the Dokka version to 2.0.0 in the `plugins {}` block of your project’s ```kotlin plugins { kotlin("jvm") version "2.1.10" - id("org.jetbrains.dokka") version "2.0.0" + id("org.jetbrains.dokka") version "%dokkaVersion%" } ``` @@ -526,15 +525,15 @@ For an example of the DGP v2 configuration, see the DGP v2 allows you to extend its functionality by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/ae3840edb4e4afd7b3e3768a5fddfe8ec0e08f31/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts). Custom plugins enable additional processing or modifications to the documentation generation process. -### Share Dokka configuration across modules +### Share Dokka configuration across subprojects -DPG v2 moves away from using `subprojects {}` or `allprojects {}` to share configuration across modules. In future Gradle versions, +DPG v2 moves away from using `subprojects {}` or `allprojects {}` to share configuration across subprojects. In future Gradle versions, using these approaches will [lead to errors](https://docs.gradle.org/current/userguide/isolated_projects.html). Follow the steps below to properly share Dokka configuration in multi-module projects [with existing convention plugins](#multi-module-projects-with-convention-plugins) or [without convention plugins](#multi-module-projects-without-convention-plugins). -After sharing the Dokka configuration, you can aggregate the documentation from multiple modules into a single output. For more information, see +After sharing the Dokka configuration, you can aggregate the documentation from multiple subprojects into a single output. For more information, see [Update documentation aggregation in multi-module projects](#update-documentation-aggregation-in-multi-module-projects). > For a multi-module project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example). @@ -543,12 +542,12 @@ After sharing the Dokka configuration, you can aggregate the documentation from #### Multi-module projects without convention plugins -If your project doesn't use convention plugins, you can still share Dokka configurations by directly configuring each module. -This involves manually setting up the shared configuration in each module's `build.gradle.kts` file. While this approach is less centralized, +If your project doesn't use convention plugins, you can still share Dokka configurations by directly configuring each subproject. +This involves manually setting up the shared configuration in each subproject's `build.gradle.kts` file. While this approach is less centralized, it avoids the need for additional setups like convention plugins. Otherwise, if your project uses convention plugins, you can also share the Dokka configuration in multi-module projects -by creating a convention plugin in the `buildSrc` directory, and then applying the plugin to your modules (subprojects). +by creating a convention plugin in the `buildSrc` directory, and then applying the plugin to your subprojects. ##### Set up the buildSrc directory @@ -600,9 +599,9 @@ After setting up the `buildSrc` directory: You need to add the shared Dokka [configuration](#adjust-configuration-options) common to all subprojects within the `dokka {}` block. Also, you don't need to specify a Dokka version. The version is already set in the `buildSrc/build.gradle.kts` file. -##### Apply the convention plugin to your modules +##### Apply the convention plugin to your subprojects -Apply the Dokka convention plugin across your modules (subprojects) by adding it to each subproject's `build.gradle.kts` file: +Apply the Dokka convention plugin across your subprojects by adding it to each subproject's `build.gradle.kts` file: ```kotlin plugins { @@ -615,13 +614,13 @@ plugins { If you already have convention plugins, create a dedicated Dokka convention plugin following [Gradle's documentation](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:convention_plugins). Then, follow the steps to [set up the Dokka convention plugin](#set-up-the-dokka-convention-plugin) and -[apply it across your modules](#apply-the-convention-plugin-to-your-modules). +[apply it across your subprojects](#apply-the-convention-plugin-to-your-subprojects). ### Update documentation aggregation in multi-module projects -Dokka can aggregate the documentation from multiple modules (subprojects) into a single output or publication. +Dokka can aggregate the documentation from multiple subprojects into a single output or publication. -As [explained](#apply-the-convention-plugin-to-your-modules), apply the Dokka plugin to all documentable subprojects before aggregating the documentation. +As [explained](#apply-the-convention-plugin-to-your-subprojects), apply the Dokka plugin to all documentable subprojects before aggregating the documentation. Aggregation in DGP v2 uses the `dependencies {}` block instead of tasks and can be added in any `build.gradle.kts` file. @@ -647,7 +646,7 @@ dependencies { ### Change directory of aggregated documentation -When DGP aggregates modules, each subproject has its own subdirectory within the aggregated documentation. +When DGP aggregates subprojects, each subproject has its own subdirectory within the aggregated documentation. In DGP v2, the aggregation mechanism has been updated to better align with Gradle conventions. DGP v2 now preserves the full subproject directory to prevent conflicts when aggregating @@ -677,7 +676,7 @@ may become outdated, potentially causing `404` errors. #### Revert to the DGP v1 directory behavior -If your project depends on the directory structure used in DGP v1, you can revert this behavior by manually specifying the module directory. +If your project depends on the directory structure used in DGP v1, you can revert this behavior by manually specifying the subproject directory. Add the following configuration to the `build.gradle.kts` file of each subproject: ```kotlin @@ -688,7 +687,7 @@ plugins { } dokka { - // Overrides the module directory to match the V1 structure + // Overrides the subproject directory to match the V1 structure modulePath.set("maths") } ``` @@ -734,10 +733,10 @@ or both formats at the same time: ```kotlin plugins { // Generates HTML documentation - id("org.jetbrains.dokka") version "2.0.0" + id("org.jetbrains.dokka") version "%dokkaVersion%" // Generates Javadoc documentation - id("org.jetbrains.dokka-javadoc") version "2.0.0" + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" // Keeping both plugin IDs generates both formats } @@ -786,73 +785,6 @@ 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 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"} - ## What's next * [Explore more DGP v2 project examples](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2). diff --git a/docs/topics/dokka-module-and-package-docs.md b/docs/topics/dokka-module-and-package-docs.md index d6c7af0baa..fdb6de0b0f 100644 --- a/docs/topics/dokka-module-and-package-docs.md +++ b/docs/topics/dokka-module-and-package-docs.md @@ -1,15 +1,15 @@ -[//]: # (title: Module documentation) +[//]: # (title: Subproject documentation) -Documentation for a module as a whole, as well as packages in that module, can be provided as separate Markdown files. +Documentation for a subproject as a whole, as well as packages in that subproject, can be provided as separate Markdown files. ## File format -Inside the Markdown file, the documentation for the module as a whole and for individual packages is introduced by the corresponding -first-level headings. The text of the heading **must** be **Module ``** for a module, and **Package ``** +Inside the Markdown file, the documentation for the subproject as a whole and for individual packages is introduced by the corresponding +first-level headings. The text of the heading **must** be **Module ``** for a subproject, and **Package ``** for a package. -The file doesn't have to contain both module and package documentation. You can have files that contain only package or -module documentation. You can even have a Markdown file per module or package. +The file doesn't have to contain both subproject and package documentation. You can have files that contain only package or +subproject documentation. You can even have a Markdown file per subproject or package. Using [Markdown syntax](https://www.markdownguide.org/basic-syntax/), you can add: * Headings up to level 6 @@ -19,12 +19,12 @@ Using [Markdown syntax](https://www.markdownguide.org/basic-syntax/), you can ad * Code blocks * Blockquotes -Here's an example file containing both module and package documentation: +Here's an example file containing both subproject and package documentation: ```text # Module kotlin-demo -This content appears under your module name. +This content appears under your subproject name. # Package org.jetbrains.kotlin.demo diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md index 8fe048d7c5..17dd15cdf0 100644 --- a/docs/topics/dokka-plugins.md +++ b/docs/topics/dokka-plugins.md @@ -1,5 +1,10 @@ [//]: # (title: Dokka plugins) +> 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"} + Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community to implement plugins for missing or very specific features that are not provided out of the box. @@ -13,11 +18,11 @@ If you want to learn how to create Dokka plugins, see ## Apply Dokka plugins -Dokka plugins are published as separate artifacts, so to apply a Dokka plugin you only need to add it as a dependency. -From there, the plugin extends Dokka by itself - no further action is needed. +Dokka plugins are published as separate artifacts, so to apply a Dokka plugin, you only need to add it as a dependency. +From there, the plugin extends Dokka by itself—no further action is needed. > Plugins that use the same extension points or work in a similar way can interfere with each other. -> This may lead to visual bugs, general undefined behaviour or even failed builds. However, it should not lead to +> This may lead to visual bugs, general undefined behavior or even failed builds. However, it should not lead to > concurrency issues since Dokka does not expose any mutable data structures or objects. > > If you notice problems like this, it's a good idea to check which plugins are applied and what they do. @@ -30,34 +35,22 @@ to your project: -> 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: -> -> * [Configure Dokka plugins](dokka-migration.md#configure-dokka-plugins) -> * [Work with multi-module projects](dokka-migration.md#share-dokka-configuration-across-modules) -> -> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). -> -> {style="note"} - -The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply plugins universally or -for a specific output format only. +The way to apply Dokka plugins is: ```kotlin -dependencies { - // Is applied universally - dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%") - - // Is applied for the single-module dokkaHtml task only - dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} - // Is applied for HTML format in multi-project builds - dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +dependencies { + dokkaPlugin("org.jetbrains.dokka:mathjax-plugin") } ``` -> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within -> subprojects as well as in their parent project. +> * Built-in plugins (like HTML and Javadoc) are always applied automatically. You only configure them and do not need dependencies for them. > +> * When documenting multi-module projects (multi-project builds), you need to [share Dokka configuration and plugins across subprojects](dokka-gradle.md#multi-project-configuration). +> {style="note"} @@ -79,7 +72,8 @@ dependencies { } ``` -> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within +> When documenting [multi-project](dokka-gradle.md#multi-project-configuration) builds, +> you need to apply Dokka plugins within > subprojects as well as in their parent project. > {style="note"} @@ -139,57 +133,32 @@ If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), Dokka plugins can also have configuration options of their own. To see which options are available, consult the documentation of the plugins you are using. -Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](dokka-html.md) -documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets -(`customStyleSheets` option), and by modifying the footer message (`footerMessage` option): +Let's have a look at how you can configure the built-in HTML plugin by adding a custom image to the assets +(`customAssets` option), +custom style sheets (`customStyleSheets` option), and a modified footer message (`footerMessage` option): -Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to -the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes: +To configure Dokka plugins in a type-safe way, use the `dokka.pluginsConfiguration {}` block: ```kotlin -import org.jetbrains.dokka.base.DokkaBase -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.base.DokkaBaseConfiguration - -buildscript { - dependencies { - classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%") - } -} - -tasks.withType().configureEach { - pluginConfiguration { - customAssets = listOf(file("my-image.png")) - customStyleSheets = listOf(file("my-styles.css")) - footerMessage = "(c) 2022 MyOrg" +dokka { + pluginsConfiguration.html { + customAssets.from("logo.png") + customStyleSheets.from("styles.css") + footerMessage.set("(c) Your Company") } } ``` -Alternatively, plugins can be configured via JSON. With this method, no additional dependencies are needed. +For an example of Dokka plugins configuration, see the +[Dokka's versioning plugin](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/versioning-multimodule-example). -```kotlin -import org.jetbrains.dokka.gradle.DokkaTask - -tasks.withType().configureEach { - val dokkaBaseConfiguration = """ - { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" - } - """ - pluginsMapConfiguration.set( - mapOf( - // fully qualified plugin name to json configuration - "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration - ) - ) -} -``` +Dokka allows you +to extend its functionality +by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/v2.1.0/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts). +Custom plugins enable additional processing or modifications to the documentation generation process. @@ -281,7 +250,7 @@ Here are some notable Dokka plugins that you might find useful: | [Versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) | Adds version selector and helps to organize documentation for different versions of your application/library | | [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid) | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs | | [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-mathjax) | Pretty prints mathematics found in KDocs | -| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java) | Renders Kotlin signatures as seen from Java's perspective | +| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java) | Renders Kotlin signatures as seen from Java's perspective | If you are a Dokka plugin author and would like to add your plugin to this list, get in touch with maintainers via [Slack](dokka-introduction.md#community) or [GitHub](https://github.com/Kotlin/dokka/). diff --git a/docs/topics/formats/dokka-html.md b/docs/topics/formats/dokka-html.md index f8e9b11b43..eb4079b153 100644 --- a/docs/topics/formats/dokka-html.md +++ b/docs/topics/formats/dokka-html.md @@ -1,23 +1,34 @@ [//]: # (title: HTML) -HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release. +> 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"} + +HTML is Dokka's default and recommended output format. +It provides support for Kotlin Multiplatform, Android, and Java projects. +Additionally, you can use the HTML format to document both single and multi-project builds. -You can see an example of the output by browsing documentation -for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). +For examples of the HTML output format, check the following docs: +* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/) +* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html) +* [Hexagon](https://hexagontk.com/stable/api/) +* [Ktor](https://api.ktor.io/) +* [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/) +* [Gradle](https://docs.gradle.org/current/kotlin-dsl/index.html) ## Generate HTML documentation HTML as an output format is supported by all runners. To generate HTML documentation, follow these steps depending on your build tool or runner: -* For [Gradle](dokka-gradle.md#generate-documentation), run `dokkaHtml` or `dokkaHtmlMultiModule` tasks. - - > These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, [the Gradle tasks to generate documentation changed](dokka-migration.md#generate-documentation-with-the-updated-task). - > - > For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). - > - {style="note"} - +* For [Gradle](dokka-gradle.md#generate-documentation), run the following tasks: + * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). + This is the recommended task for most users. When using this task in IntelliJ IDEA, it logs a clickable link to the output. + * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. This task exposes the output directory + as an `@OutputDirectory`. Use this task when you need to consume the generated files in other Gradle tasks, such + as uploading them to a server, moving them into a GitHub Pages directory, or packaging them into a `javadoc.jar`. + This task is intentionally not shown in Gradle task groups because it is not meant for everyday use. * For [Maven](dokka-maven.md#generate-documentation), run the `dokka:dokka` goal. * For [CLI runner](dokka-cli.md#generate-documentation), run with HTML dependencies set. @@ -32,62 +43,26 @@ your build tool or runner: ## Configuration -HTML format is Dokka's base format, so it is configurable through `DokkaBase` and `DokkaBaseConfiguration` -classes: +HTML format is Dokka's base format, and you can include configuration options: -Via type-safe Kotlin DSL: - ```kotlin -import org.jetbrains.dokka.base.DokkaBase -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.base.DokkaBaseConfiguration - -buildscript { - dependencies { - classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%") - } -} - -tasks.withType().configureEach { - pluginConfiguration { - customAssets = listOf(file("my-image.png")) - customStyleSheets = listOf(file("my-styles.css")) - footerMessage = "(c) 2022 MyOrg" - separateInheritedMembers = false - templatesDir = file("dokka/templates") - mergeImplicitExpectActualDeclarations = false +// build.gradle.kts + +dokka { + pluginsConfiguration.html { + customAssets.from("logo.png") + customStyleSheets.from("styles.css") + footerMessage.set("(c) Your Company") + separateInheritedMembers.set(false) + templatesDir.set(file("dokka/templates")) + mergeImplicitExpectActualDeclarations.set(false) } } ``` -Via JSON: - -```kotlin -import org.jetbrains.dokka.gradle.DokkaTask - -tasks.withType().configureEach { - val dokkaBaseConfiguration = """ - { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg", - "separateInheritedMembers": false, - "templatesDir": "${file("dokka/templates")}", - "mergeImplicitExpectActualDeclarations": false - } - """ - pluginsMapConfiguration.set( - mapOf( - // fully qualified plugin name to json configuration - "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration - ) - ) -} -``` - @@ -173,7 +148,7 @@ Via [JSON configuration](dokka-cli.md#run-with-json-configuration): ### Configuration options -The table below contains all of the possible configuration options and their purpose. +The table below contains all the possible configuration options and their purpose: | **Option** | **Description** | |-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -213,8 +188,16 @@ You can provide your own images to be bundled with documentation by using the `c These files are copied to the `/images` directory. +You can use the `customAssets` property with collections of +files +[(`FileCollection`)](https://docs.gradle.org/8.10/userguide/lazy_configuration.html#working_with_files_in_lazy_properties): + +```kotlin +customAssets.from("example.png", "example2.png") +``` + It's possible to override Dokka's images and icons by providing files with the same name. The most -useful and relevant one being `logo-icon.svg`, which is the image that's used in the header. The rest is mostly icons. +useful and relevant one is `logo-icon.svg`, which is the image used in the header. The rest is mostly icons. You can find all images used by Dokka on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-base/src/main/resources/dokka/images). @@ -240,7 +223,7 @@ You can modify text in the footer by using the `footerMessage` [configuration op Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) templates used for generating documentation pages. -You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on. +You can change the header completely, add your own banners/menus/search, load analytics, change body styling, and so on. Dokka uses the following templates: @@ -252,7 +235,8 @@ Dokka uses the following templates: | `includes/page_metadata.ftl` | Metadata used within `` container. | | `includes/source_set_selector.ftl` | [The source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) selector in the header. | -The base template is `base.ftl` and it includes all of the remaining listed templates. You can find the source code for all of Dokka's templates +The base template is `base.ftl` and it includes all the remaining listed templates. +You can find the source code for all of Dokka's templates [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-base/src/main/resources/dokka/templates). You can override any template by using the `templatesDir` [configuration option](#configuration). Dokka searches @@ -272,11 +256,11 @@ The following variables are available inside all templates: | `${pathToRoot}` | The path to root from the current page. It's useful for locating assets and is available only within the `template_cmd` directive. | Variables `projectName` and `pathToRoot` are available only within the `template_cmd` directive as they require more -context and thus they need to be resolved at later stages by the [MultiModule](dokka-gradle.md#multi-project-builds) task: +context, and thus they need to be resolved at later stages: ```html <@template_cmd name="projectName"> - ${projectName} + ${projectName} ``` @@ -288,4 +272,4 @@ You can also use the following Dokka-defined [directives](https://freemarker.apa |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `<@content/>` | The main page content. | | `<@resources/>` | Resources such as scripts and stylesheets. | -| `<@version/>` | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) is applied, it is replaced with a version navigator. | +| `<@version/>` | The subproject version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) is applied, it is replaced with a version navigator. | diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md index a7f42c463e..21d1e7b9b9 100644 --- a/docs/topics/formats/dokka-javadoc.md +++ b/docs/topics/formats/dokka-javadoc.md @@ -1,10 +1,10 @@ [//]: # (title: Javadoc) + -> The Javadoc output format is still in Alpha, so you may find bugs and experience migration issues when using it. -> Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed. -> **You use it at your own risk.** +> 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="warning"} +{style="note"} Dokka's Javadoc output format is a lookalike of Java's [Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). @@ -12,34 +12,39 @@ Dokka's Javadoc output format is a lookalike of Java's It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation or an exact copy. -![Screenshot of javadoc output format](javadoc-format-example.png){width=706} +![Screenshot of Javadoc output format](javadoc-format-example.png){width=706} All Kotlin code and signatures are rendered as seen from Java's perspective. This is achieved with our [Kotlin as Java Dokka plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java), which comes bundled and applied by default for this format. The Javadoc output format is implemented as a [Dokka plugin](dokka-plugins.md), and it is maintained by the Dokka team. -It is open source and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-javadoc). +It is open source, +and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-javadoc). ## Generate Javadoc documentation -> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, [the Gradle tasks to generate documentation changed](dokka-migration.md#select-documentation-output-format). -> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). +> The Javadoc format does not support multi-project builds or Kotlin Multiplatform projects. > -> The Javadoc format does not support multiplatform projects. -> -{style="warning"} +{style="tip"} -The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Javadoc output format included. You can use the following tasks: +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Javadoc output format included. +You need to apply the corresponding plugin id in the `plugins {}` block of your project's `build.gradle.kts` file: + +```kotlin +plugins { + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" +} +``` + +Once you applied the plugin, you can run the following tasks: -| **Task** | **Description** | -|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `dokkaJavadoc` | Generates Javadoc documentation for a single project. | -| `dokkaJavadocCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJavadoc` for every subproject and merges all outputs into a single virtual project. | +* `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). +* `dokkaGeneratePublicationJavadoc` to generate documentation only in Javadoc format. The `javadoc.jar` file can be generated separately. For more information, see [Building `javadoc.jar`](dokka-gradle.md#build-javadoc-jar). diff --git a/docs/topics/formats/dokka-markdown.md b/docs/topics/formats/dokka-markdown.md index a78f42ac17..1e195f4f5d 100644 --- a/docs/topics/formats/dokka-markdown.md +++ b/docs/topics/formats/dokka-markdown.md @@ -1,11 +1,11 @@ [//]: # (title: Markdown) + -> The Markdown output formats are still in Alpha, so you may find bugs and experience migration issues when using them. -> **You use them at your own risk.** +> 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). > -> Experimental formats like Markdown and Jekyll are not supported by default in Dokka 2.0.0. -> Workarounds for enabling these formats will be added soon. -{style="warning"} +{style="note"} + Dokka is able to generate documentation in [GitHub Flavored](#gfm) and [Jekyll](#jekyll) compatible Markdown. @@ -23,18 +23,69 @@ The GFM output format generates documentation in [GitHub Flavored Markdown](http -The [Gradle plugin for Dokka](dokka-gradle.md) comes with the GFM output format included. You can use the following tasks with it: +The GFM format is implemented as a Dokka plugin, +but to properly integrate it with the [Dokka Gradle Plugin](dokka-gradle.md). +You need to create a Dokka Format Gradle plugin: + +```kotlin +@OptIn(InternalDokkaGradlePluginApi::class) +abstract class DokkaMarkdownPlugin : DokkaFormatPlugin(formatName = "markdown") { + override fun DokkaFormatPlugin.DokkaFormatPluginContext.configure() { + project.dependencies { + // Sets up current project generation + dokkaPlugin(dokka("gfm-plugin")) + + // Sets up multimodule generation + formatDependencies.dokkaPublicationPluginClasspathApiOnly.dependencies.addLater( + dokka("gfm-template-processing-plugin") + ) + } + } +} +``` + +It's possible to declare the Dokka Format Gradle plugin directly in the build script, +as a separate file in build-logic, or inside a convention plugin. + +After you declared the Dokka Format Gradle plugin, +apply it in every place where the Dokka plugin is applied, including the project with aggregation +(such as the root project). + +If you are using a convention plugin, you can add it like this: + +```kotlin +plugins { + id("org.jetbrains.dokka") +} + +// Declares Markdown Gradle plugin +@OptIn(InternalDokkaGradlePluginApi::class) +abstract class DokkaMarkdownPlugin : DokkaFormatPlugin(formatName = "markdown") { + override fun DokkaFormatPlugin.DokkaFormatPluginContext.configure() { + project.dependencies { + // Sets up current project generation + dokkaPlugin(dokka("gfm-plugin")) + + // Sets up multimodule generation + formatDependencies.dokkaPublicationPluginClasspathApiOnly.dependencies.addLater( + dokka("gfm-template-processing-plugin") + ) + } + } +} +// Applies the plugin +apply() +``` -| **Task** | **Description** | -|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `dokkaGfm` | Generates GFM documentation for a single project. | -| `dokkaGfmMultiModule` | A [`MultiModule`](dokka-gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. It generates documentation for subprojects and collects all outputs in a single place with a common table of contents. | -| `dokkaGfmCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaGfm` for every subproject and merges all outputs into a single virtual project. | +Once you applied the plugin, you can run the following tasks: +* `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). +* `dokkaGenerateMarkdown` to generate documentation only in Markdown format. -Since GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to apply it as a plugin +Since the GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), +you need to apply it as a plugin dependency: ```xml @@ -61,7 +112,7 @@ For more information, see the Maven plugin documentation for [Other output forma -Since GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to +Since the GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to [download the JAR file](https://repo1.maven.org/maven2/org/jetbrains/dokka/gfm-plugin/%dokkaVersion%/gfm-plugin-%dokkaVersion%.jar) and pass it to `pluginsClasspath`. @@ -92,8 +143,6 @@ For more information, see the CLI runner's documentation for [Other output forma -You can find the source code [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-gfm). - ## Jekyll The Jekyll output format generates documentation in [Jekyll](https://jekyllrb.com/) compatible Markdown. @@ -101,18 +150,46 @@ The Jekyll output format generates documentation in [Jekyll](https://jekyllrb.co -The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Jekyll output format included. You can use the following tasks with it: +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Jekyll output format included. + +Similar to [GFM](#gfm), you need to +declare the Dokka Format Gradle plugin directly in the build script, +as a separate file in build-logic, or inside a convention plugin. +Then, apply it in every place where the Dokka plugin is applied: + +```kotlin +plugins { + id("org.jetbrains.dokka") +} + +// Declares Markdown Gradle plugin +@OptIn(InternalDokkaGradlePluginApi::class) +abstract class DokkaMarkdownPlugin : DokkaFormatPlugin(formatName = "markdown") { + override fun DokkaFormatPlugin.DokkaFormatPluginContext.configure() { + project.dependencies { + // Sets up current project generation + dokkaPlugin(dokka("jekyll-plugin")) + + // Sets up multimodule generation + formatDependencies.dokkaPublicationPluginClasspathApiOnly.dependencies.addLater( + dokka("jekyll-template-processing-plugin") + ) + } + } +} +// Applies the plugin +apply() +``` -| **Task** | **Description** | -|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `dokkaJekyll` | Generates Jekyll documentation for a single project. | -| `dokkaJekyllMultiModule` | A [`MultiModule`](dokka-gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. It generates documentation for subprojects and collects all outputs in a single place with a common table of contents. | -| `dokkaJekyllCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJekyll` for every subproject and merges all outputs into a single virtual project. | +Once you applied the plugin, you can run the following tasks: +* `dokkaGenerateMarkdown` to generate documentation only in Markdown format. +* `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). -Since Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to apply it as a plugin +Since the Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), +you need to apply it as a plugin dependency: ```xml @@ -139,7 +216,7 @@ For more information, see the Maven plugin's documentation for [Other output for -Since Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to +Since the Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to [download the JAR file](https://repo1.maven.org/maven2/org/jetbrains/dokka/jekyll-plugin/%dokkaVersion%/jekyll-plugin-%dokkaVersion%.jar). This format is also based on [GFM](#gfm) format, so you need to provide it as a dependency as well. Both JARs need to be passed to `pluginsClasspath`: diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md index 3a7b575015..6ad94b420c 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -1,31 +1,26 @@ [//]: # (title: Gradle) -> 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"} - To generate documentation for a Gradle-based project, you can use the [Gradle plugin for Dokka](https://plugins.gradle.org/plugin/org.jetbrains.dokka). -It comes with basic autoconfiguration for your project, has convenient [Gradle tasks](#generate-documentation) for -generating documentation, and provides a great deal of [configuration options](#configuration-options) to +The Dokka Gradle plugin (DGP) comes with basic autoconfiguration for your project, +includes [Gradle tasks](#generate-documentation) for +generating documentation, and provides [configuration options](#configuration-options) to customize the output. -You can play around with Dokka and see how it can be configured for various projects by visiting our -[Gradle example projects](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle). +You can play around with Dokka and explore how to configure it for various projects in our +[Gradle example projects](https://github.com/Kotlin/dokka/tree/2.0.0/examples/gradle-v2). ## Apply Dokka The recommended way of applying the Gradle plugin for Dokka is with the -[plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block): +[plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). +Add it in the `plugins {}` block of your project’s `build.gradle.kts` file: @@ -48,110 +43,121 @@ plugins { -When documenting [multi-project](#multi-project-builds) builds, you need to apply the Gradle plugin for Dokka -within subprojects as well. You can use `allprojects {}` or `subprojects {}` Gradle configurations to achieve that: +When documenting multi-project builds, you don't need to apply the plugin explicitly to every subproject you want to document. +Instead, +Dokka expects you to share configuration across subprojects using convention plugins or manual configuration per subproject. +For more information, see +how to configure [single-project](#single-project-configuration) and [multi-project](#multi-project-configuration) builds. - - +> * Under the hood, +> Dokka uses the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) +> to automatically configure [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) +> for which documentation is generated. Make sure to apply the Kotlin Gradle Plugin or +> [configure source sets](#source-set-configuration) manually. +> +> * If you are using Dokka in a +> [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins), +> add the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) +> as a dependency to ensure it works properly. +> +{style="tip"} -```kotlin -subprojects { - apply(plugin = "org.jetbrains.dokka") -} -``` +If you are not able to use the plugins DSL, you can apply the plugin using +[the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application). - - +## Enable build cache and configuration cache -```groovy -subprojects { - apply plugin: 'org.jetbrains.dokka' -} -``` +DGP supports Gradle build cache and configuration cache, improving build performance. - - +* 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 ). -See [Configuration examples](#configuration-examples) if you are not sure where to apply Dokka. +## Generate documentation -> Under the hood, Dokka uses the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) -> to perform autoconfiguration of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) -> for which documentation is to be generated. Make sure to apply the Kotlin Gradle Plugin or -> [configure source sets](#source-set-configuration) manually. -> -{style="note"} +The Dokka Gradle plugin comes with [HTML](dokka-html.md) and [Javadoc](dokka-javadoc.md) output formats +built in. +Additionally, you can manually enable the [Markdown](dokka-markdown.md) format. -> If you are using Dokka in a -> [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins), -> you need to add the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) -> as a dependency for it to work properly. -> -{style="note"} +Use the following Gradle task to generate documentation: -If you cannot use the plugins DSL for some reason, you can use -[the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application) of applying -plugins. +```shell +./gradlew :dokkaGenerate +``` -## Generate documentation +The key behavior of the `dokkaGenerate` Gradle task is: -The Gradle plugin for Dokka comes with [HTML](dokka-html.md), [Markdown](dokka-markdown.md) and [Javadoc](dokka-javadoc.md) output formats -built in. It adds a number of tasks for generating documentation, both for [single](#single-project-builds) -and [multi-project](#multi-project-builds) builds. +* This task generates documentation for both [single](#single-project-configuration) + and [multi-project](#multi-project-configuration) builds. +* By default, the documentation output format is HTML. + You can also generate Javadoc or both HTML and Javadoc formats + by [adding the appropriate plugins](#configure-documentation-output-format). +* The generated documentation is automatically placed in the `build/dokka/html` + directory for both single and multi-project builds. + You can [change the location (`outputDirectory`)](#general-configuration). -### Single-project builds +### Configure documentation output format -Use the following tasks to build documentation for simple, single-project applications and libraries: +> The Javadoc output format is in [Alpha](https://kotlinlang.org/docs/components-stability.html#stability-levels-explained). +> You may find bugs and experience migration issues when using it. +> Successful integration with tools that accept Javadoc as input is not guaranteed. +> Use it at your own risk. +> +{style="note"} -| **Task** | **Description** | -|-------------|----------------------------------------------------------| -| `dokkaHtml` | Generates documentation in [HTML](dokka-html.md) format. | +You can choose to generate the API documentation in HTML, Javadoc, +or both formats at the same time: -#### Experimental formats +1. Place the corresponding plugin `id` in the `plugins {}` block of your project's `build.gradle.kts` file: -| **Task** | **Description** | -|----------------|-------------------------------------------------------------------------------------------| -| `dokkaGfm` | Generates documentation in [GitHub Flavored Markdown](dokka-markdown.md#gfm) format. | -| `dokkaJavadoc` | Generates documentation in [Javadoc](dokka-javadoc.md) format. | -| `dokkaJekyll` | Generates documentation in [Jekyll compatible Markdown](dokka-markdown.md#jekyll) format. | + ```kotlin + plugins { + // Generates HTML documentation + id("org.jetbrains.dokka") version "%dokkaVersion%" -By default, generated documentation is located in the `build/dokka/{format}` directory of your project. -The output location, among other things, can be [configured](#configuration-examples). + // Generates Javadoc documentation + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" -### Multi-project builds + // Keeping both plugin IDs generates both formats + } + ``` -For documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), make sure -that you [apply the Gradle plugin for Dokka](#apply-dokka) within subprojects that you want to generate documentation -for, as well as in their parent project. +2. Run the corresponding Gradle task. -#### MultiModule tasks + Here is a list of the plugin `id` and Gradle task that correspond to each format: -`MultiModule` tasks generate documentation for each subproject individually via [`Partial`](#partial-tasks) tasks, -collect and process all outputs, and produce complete documentation with a common table of contents and resolved -cross-project references. + | | **HTML** | **Javadoc** | **Both** | + |-------------|-------------------------------------------|----------------------------------------------|-----------------------------------| + | Plugin `id` | `id("org.jetbrains.dokka")` | `id("org.jetbrains.dokka-javadoc")` | Use both HTML and Javadoc plugins | + | Gradle task | `./gradlew :dokkaGeneratePublicationHtml` | `./gradlew :dokkaGeneratePublicationJavadoc` | `./gradlew :dokkaGenerate` | -Dokka creates the following tasks for **parent** projects automatically: + > The `dokkaGenerate` task generates documentation in all available formats based on the applied plugins. + > If both the HTML and Javadoc plugins are applied, + > you can choose to generate only HTML by running the `dokkaGeneratePublicationHtml` task, + > or only Javadoc by running the `dokkaGeneratePublicationJavadoc` task. + > + {style="tip"} -| **Task** | **Description** | -|------------------------|------------------------------------------------------------------------------| -| `dokkaHtmlMultiModule` | Generates multi-module documentation in [HTML](dokka-html.md) output format. | +The Markdown output format (including GFM and Jekyll) is not supported by default, +but you can [enable it manually](dokka-markdown.md). -#### Experimental formats (multi-module) +### Aggregate documentation output in multi-project builds -| **Task** | **Description** | -|--------------------------|---------------------------------------------------------------------------------------------------------------| -| `dokkaGfmMultiModule` | Generates multi-module documentation in [GitHub Flavored Markdown](dokka-markdown.md#gfm) output format. | -| `dokkaJekyllMultiModule` | Generates multi-module documentation in [Jekyll compatible Markdown](dokka-markdown.md#jekyll) output format. | +Dokka can aggregate documentation from multiple subprojects into a single output or publication. -> The [Javadoc](dokka-javadoc.md) output format does not have a `MultiModule` task, but a [`Collector`](#collector-tasks) task can -> be used instead. -> -{style="note"} +You have to [apply the Dokka plugin](#apply-the-convention-plugin-to-your-subprojects) to +all documentable subprojects before aggregating the documentation. -By default, you can find ready-to-use documentation under `{parentProject}/build/dokka/{format}MultiModule` directory. +To aggregate documentation from multiple subprojects, add the `dependencies {}` +block in the `build.gradle.kts` file of the root project: -#### MultiModule results +```kotlin +dependencies { + dokka(project(":childProjectA:")) + dokka(project(":childProjectB:")) +} +``` -Given a project with the following structure: +Given a project with the following structure: ```text . @@ -164,70 +170,40 @@ Given a project with the following structure: └── ChildProjectBClass ``` -These pages are generated after running `dokkaHtmlMultiModule`: +The generated documentation is aggregated as follows: ![Screenshot for output of dokkaHtmlMultiModule task](dokkaHtmlMultiModule-example.png){width=600} -See our [multi-module project example](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-multimodule-example) +See our [multi-project example](https://github.com/Kotlin/dokka/tree/2.0.0/examples/gradle-v2/multimodule-example) for more details. -#### Collector tasks - -Similar to `MultiModule` tasks, `Collector` tasks are created for each parent project: `dokkaHtmlCollector`, -`dokkaGfmCollector`, `dokkaJavadocCollector` and `dokkaJekyllCollector`. - -A `Collector` task executes the corresponding [single-project task](#single-project-builds) for each subproject (for -example, -`dokkaHtml`), and merges all outputs into a single virtual project. - -The resulting documentation looks as if you have a single-project -build that contains all declarations from the subprojects. - -> Use the `dokkaJavadocCollector` task if you need to create Javadoc documentation for your multi-project build. -> -{style="tip"} +#### Directory of aggregated documentation -#### Collector results +When DGP aggregates subprojects, each subproject has its own subdirectory within the aggregated documentation. +DGP ensures each subproject has a unique directory by retaining the full project structure. -Given a project with the following structure: +For example, given a project with an aggregation in `:turbo-lib` and a nested subproject `:turbo-lib:maths`, +the generated documentation is placed under: ```text -. -└── parentProject/ - ├── childProjectA/ - │ └── demo/ - │ └── ChildProjectAClass - └── childProjectB/ - └── demo/ - └── ChildProjectBClass +turbo-lib/build/dokka/html/turbo-lib/maths/ ``` -These pages are generated after running `dokkaHtmlCollector`: - -![Screenshot for output of dokkaHtmlCollector task](dokkaHtmlCollector-example.png){width=706} - -See our [multi-module project example](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-multimodule-example) -for more details. - -#### Partial tasks +You can revert this behavior by manually specifying the subproject directory. +Add the following configuration to the `build.gradle.kts` file of each subproject: -Each subproject has `Partial` tasks created for it: `dokkaHtmlPartial`,`dokkaGfmPartial`, -and `dokkaJekyllPartial`. - -These tasks are not intended to be run independently, they are called by the parent's -[MultiModule](#multimodule-tasks) task. - -However, you can [configure](#subproject-configuration) `Partial` tasks to customize Dokka for your subprojects. +```kotlin +// /turbo-lib/maths/build.gradle.kts -> Output generated by `Partial` tasks contains unresolved HTML templates and references, so it cannot be used -> on its own without post-processing done by the parent's [`MultiModule`](#multimodule-tasks) task. -> -{style="warning"} +plugins { + id("org.jetbrains.dokka") +} -> If you want to generate documentation for a single subproject only, use -> [single-project tasks](#single-project-builds). For example, `:subprojectName:dokkaHtml`. -> -{style="note"} +dokka { + // Overrides the subproject directory + modulePath.set("maths") +} +``` ## Build javadoc.jar @@ -245,15 +221,17 @@ tasks. One for generating documentation in [HTML](dokka-html.md) format and anot ```kotlin -tasks.register("dokkaHtmlJar") { - dependsOn(tasks.dokkaHtml) - from(tasks.dokkaHtml.flatMap { it.outputDirectory }) - archiveClassifier.set("html-docs") +// To generate documentation in HTML +val dokkaHtmlJar by tasks.registering(Jar::class) { + description = "A HTML Documentation JAR containing Dokka HTML" + from(tasks.dokkaGeneratePublicationHtml.flatMap { it.outputDirectory }) + archiveClassifier.set("html-doc") } -tasks.register("dokkaJavadocJar") { - dependsOn(tasks.dokkaJavadoc) - from(tasks.dokkaJavadoc.flatMap { it.outputDirectory }) +// To generate documentation in Javadoc +val dokkaJavadocJar by tasks.registering(Jar::class) { + description = "A Javadoc JAR containing Dokka Javadoc" + from(tasks.dokkaGeneratePublicationJavadoc.flatMap { it.outputDirectory }) archiveClassifier.set("javadoc") } ``` @@ -298,8 +276,9 @@ see [Multi-project configuration](#multi-project-configuration). ### Single-project configuration -Single-project builds usually have only one `build.gradle.kts` or `build.gradle` file in the root of the project, -and typically have the following structure: +Single-project builds usually have only one `build.gradle.kts` +or `build.gradle` file in the root of the project. +They can be either single-platform or multiplatform and typically have the following structure: @@ -366,26 +345,30 @@ Multiplatform: -In such projects, you need to apply Dokka and its configuration in the root `build.gradle.kts` or `build.gradle` file. - -You can configure tasks and output formats individually: +Apply the Dokka Gradle Plugin in your root `build.gradle.kts` file and configure it using the top-level `dokka {}` DSL: -Inside `./build.gradle.kts`: - ```kotlin plugins { id("org.jetbrains.dokka") version "%dokkaVersion%" } -tasks.dokkaHtml { - outputDirectory.set(layout.buildDirectory.dir("documentation/html")) -} +dokka { + dokkaPublications.html { + moduleName.set("MyProject") + outputDirectory.set(layout.buildDirectory.dir("documentation/html")) + includes.from("README.md") + } -tasks.dokkaGfm { - outputDirectory.set(layout.buildDirectory.dir("documentation/markdown")) + dokkaSourceSets.main { + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl.set(URI("https://github.com/your-repo")) + remoteLineSuffix.set("#L") + } + } } ``` @@ -411,80 +394,17 @@ dokkaGfm { -Or you can configure all tasks and output formats at the same time: - - - - -Inside `./build.gradle.kts`: - -```kotlin -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.gradle.DokkaTaskPartial -import org.jetbrains.dokka.DokkaConfiguration.Visibility - -plugins { - id("org.jetbrains.dokka") version "%dokkaVersion%" -} - -// Configure all single-project Dokka tasks at the same time, -// such as dokkaHtml, dokkaJavadoc and dokkaGfm. -tasks.withType().configureEach { - dokkaSourceSets.configureEach { - documentedVisibilities.set( - setOf( - Visibility.PUBLIC, - Visibility.PROTECTED, - ) - ) - - perPackageOption { - matchingRegex.set(".*internal.*") - suppress.set(true) - } - } -} -``` - - - - -Inside `./build.gradle`: - -```groovy -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.gradle.DokkaTaskPartial -import org.jetbrains.dokka.DokkaConfiguration.Visibility - -plugins { - id 'org.jetbrains.dokka' version '%dokkaVersion%' -} - -// Configure all single-project Dokka tasks at the same time, -// such as dokkaHtml, dokkaJavadoc and dokkaGfm. -tasks.withType(DokkaTask.class) { - dokkaSourceSets.configureEach { - documentedVisibilities.set([ - Visibility.PUBLIC, - Visibility.PROTECTED - ]) - - perPackageOption { - matchingRegex.set(".*internal.*") - suppress.set(true) - } - } -} -``` - - - +This configuration applies Dokka to your project, +sets up the documentation output directory, and defines the main source set. +You can extend it further by adding custom assets, visibility filters, +or plugin configurations within the same `dokka {}` block. +For more information, see [Configuration options](#configuration-options). ### Multi-project configuration -Gradle's [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html) are more complex -in structure and configuration. They usually have multiple nested `build.gradle.kts` or `build.gradle` files, and -typically have the following structure: +[Multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html) +usually contain several +nested `build.gradle.kts` files and have a structure similar to the following: @@ -531,188 +451,236 @@ typically have the following structure: -In this case, there are multiple ways of applying and configuring Dokka. - -#### Subproject configuration - -To configure subprojects in a multi-project build, you need to configure [`Partial`](#partial-tasks) tasks. +Single and multi-project documentation share the same +[configuration model using the top-level `dokka {}` DSL](#single-project-configuration). +In multi-project builds, +you configure Dokka in the root project and can optionally share settings across subprojects. -You can configure all subprojects at the same time in the root `build.gradle.kts` or `build.gradle` file, -using Gradle's `allprojects {}` or `subprojects {}` configuration blocks: +To share Dokka configuration across subprojects, you can use either: - - +* [Direct configuration in multi-project builds requiring convention plugins](#direct-configuration-in-multi-project-builds-requiring-convention-plugins) +* [Convention plugins](#multi-project-builds-with-convention-plugins) -In the root `./build.gradle.kts`: +After sharing Dokka configuration, you can aggregate the documentation from multiple subprojects into a single output. +For more information, see +[Aggregate documentation output in multi-project-builds](#aggregate-documentation-output-in-multi-project-builds). -```kotlin -import org.jetbrains.dokka.gradle.DokkaTaskPartial +> For a multi-project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example). +> +{style="tip"} -plugins { - id("org.jetbrains.dokka") version "%dokkaVersion%" -} +#### Direct configuration in multi-project builds requiring convention plugins -subprojects { - apply(plugin = "org.jetbrains.dokka") +If your project doesn't use convention plugins, you can share Dokka configurations by directly configuring each subproject. +This involves manually setting up the shared configuration in each subproject's `build.gradle.kts` file. +While this approach is less centralized, +it avoids the need for additional setups like convention plugins. - // configure only the HTML task - tasks.dokkaHtmlPartial { - outputDirectory.set(layout.buildDirectory.dir("docs/partial")) - } +Follow the next steps to configure your multi-project builds without convention plugins. - // configure all format tasks at once - tasks.withType().configureEach { - dokkaSourceSets.configureEach { - includes.from("README.md") - } - } -} -``` +##### Set up the buildSrc directory - - +1. In your project root, create a `buildSrc` directory containing two files: -In the root `./build.gradle`: + * `settings.gradle.kts` + * `build.gradle.kts` -```groovy -import org.jetbrains.dokka.gradle.DokkaTaskPartial +2. In the `buildSrc/settings.gradle.kts` file, add the following snippet: -plugins { - id 'org.jetbrains.dokka' version '%dokkaVersion%' -} + ```kotlin + rootProject.name = "buildSrc" + ``` -subprojects { - apply plugin: 'org.jetbrains.dokka' +3. In the `buildSrc/build.gradle.kts` file, add the following snippet: - // configure only the HTML task - dokkaHtmlPartial { - outputDirectory.set(file("build/docs/partial")) + ```kotlin + plugins { + `kotlin-dsl` } - - // configure all format tasks at once - tasks.withType(DokkaTaskPartial.class) { - dokkaSourceSets.configureEach { - includes.from("README.md") - } + + repositories { + mavenCentral() + gradlePluginPortal() } -} -``` + + dependencies { + implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0") + } + ``` - - +##### Set up the Dokka convention plugin -Alternatively, you can apply and configure Dokka within subprojects individually. +After setting up the `buildSrc` directory, set up the Dokka convention plugin: -For example, to have specific settings for the `subproject-A` subproject only, you need to apply the following code -inside `./subproject-A/build.gradle.kts`: +1. Create a `buildSrc/src/main/kotlin/dokka-convention.gradle.kts` file to host the [convention plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:convention_plugins). +2. In the `dokka-convention.gradle.kts` file, add the following snippet: - - - -Inside `./subproject-A/build.gradle.kts`: + ```kotlin + plugins { + id("org.jetbrains.dokka") + } -```kotlin -apply(plugin = "org.jetbrains.dokka") + dokka { + // The shared configuration goes here + } + ``` -// configuration for subproject-A only. -tasks.dokkaHtmlPartial { - outputDirectory.set(layout.buildDirectory.dir("docs/partial")) -} -``` + You need to add the shared Dokka [configuration](#configuration-options) common to all subprojects within the `dokka {}` + block. + Also, you don't need to specify a Dokka version. + The version is already set in the `buildSrc/build.gradle.kts` file. - - +##### Apply the convention plugin to your subprojects -Inside `./subproject-A/build.gradle`: +Apply the Dokka convention plugin across your subprojects by adding it to each subproject's `build.gradle.kts` +file: -```groovy -apply plugin: 'org.jetbrains.dokka' - -// configuration for subproject-A only. -dokkaHtmlPartial { - outputDirectory.set(file("build/docs/partial")) +```kotlin +plugins { + id("dokka-convention") } ``` - - +#### Multi-project builds with convention plugins -#### Parent project configuration +If you already have convention plugins, +create a dedicated Dokka convention plugin following [Gradle's documentation](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:convention_plugins). -If you want to configure something which is universal across all documentation and does not belong to the -subprojects - in other words, it's a property of the parent project - you need to configure the -[`MultiModule`](#multimodule-tasks) tasks. +Then, follow the steps to [set up the Dokka convention plugin](#set-up-the-dokka-convention-plugin) and +[apply it across your subprojects](#apply-the-convention-plugin-to-your-subprojects). -For example, if you want to change the name of your project which is used in the header of the HTML documentation, -you need to apply the following inside the root `build.gradle.kts` or `build.gradle` file: - - - +#### Parent project configuration -In the root `./build.gradle.kts` file: +In multi-project builds, you can configure settings that apply to the entire documentation in the root project. +This can include defining the output format, output directory, documentation subproject name, +aggregating documentation from all +subprojects, and other [configuration options](#configuration-options): ```kotlin plugins { id("org.jetbrains.dokka") version "%dokkaVersion%" } -tasks.dokkaHtmlMultiModule { - moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +dokka { + // Sets properties for the whole project + dokkaPublications.html { + moduleName.set("My Project") + outputDirectory.set(layout.buildDirectory.dir("docs/html")) + includes.from("README.md") + } + + dokkaSourceSets.configureEach { + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) + } +} + +// Aggregates subproject documentation +dependencies { + dokka(project(":childProjectA")) + dokka(project(":childProjectB")) } ``` - - - -In the root `./build.gradle` file: +Additionally, each subproject can have its own `dokka {}` block if it needs custom configuration. +In the following example, the subproject applies the Dokka plugin, sets a custom subproject name, +and includes additional documentation from its `README.md` file: -```groovy +```kotlin +// subproject/build.gradle.kts plugins { - id 'org.jetbrains.dokka' version '%dokkaVersion%' + id("org.jetbrains.dokka") } -dokkaHtmlMultiModule { - moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +dokka { + dokkaPublications.html { + moduleName.set("Child Project A") + includes.from("README.md") + } } ``` - - - ## Configuration options Dokka has many configuration options to tailor your and your reader's experience. Below are some examples and detailed descriptions for each configuration section. You can also find an example -with [all configuration options](#complete-configuration) applied at the bottom of the page. +with [all configuration options](#complete-configuration) applied. See [Configuration examples](#configuration-examples) for more details on where to apply configuration blocks and how. ### General configuration -Here is an example of general configuration of any Dokka task, regardless of source set or package: +Here is an example of the general Dokka Gradle plugin configuration. Use the top-level `dokka {}` DSL configuration. + +In DGP, `dokkaPublications` is the central way to declare Dokka publication configurations. +The default publications +are [`html`](dokka-html.md), [`javadoc`](dokka-javadoc.md), and [`gfm`](dokka-markdown.md). + +The syntax of `build.gradle.kts` files differs from regular `.kt` +files (such as those used for custom Gradle plugins) because Gradle's Kotlin DSL uses type-safe accessors: - + ```kotlin -import org.jetbrains.dokka.gradle.DokkaTask +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { - moduleName.set(project.name) - moduleVersion.set(project.version.toString()) - outputDirectory.set(layout.buildDirectory.dir("dokka/$name")) - failOnWarning.set(false) - suppressObviousFunctions.set(true) - suppressInheritedMembers.set(false) - offlineMode.set(false) - - // .. - // source set configuration section - // .. +dokka { + dokkaPublications.html { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(layout.buildDirectory.dir("dokka/html")) + failOnWarning.set(false) + suppressInheritedMembers.set(false) + offlineMode.set(false) + suppressObviousFunctions.set(true) + includes.from(project.files(), "packages.md", "extra.md") + + // Output directory for additional files + // Use this block when you want to change the output directory and include extra files + outputDirectory.set(rootDir.resolve("docs/api/0.x")) + includes.from(project.layout.projectDirectory.file("README.md")) + } +} +``` + + + + +```kotlin +// CustomPlugin.kt + +import org.gradle.api.Plugin +import org.gradle.api.Project +import org.jetbrains.dokka.gradle.DokkaExtension + +abstract class CustomPlugin : Plugin { + override fun apply(project: Project) { + project.plugins.apply("org.jetbrains.dokka") + + project.extensions.configure(DokkaExtension::class.java) { dokka -> + + dokka.moduleName.set(project.name) + dokka.moduleVersion.set(project.version.toString()) + + dokka.dokkaPublications.named("html") { publication -> + // Standard output directory for HTML documentation + publication.outputDirectory.set(project.layout.buildDirectory.dir("dokka/html")) + publication.failOnWarning.set(true) + publication.suppressInheritedMembers.set(true) + publication.offlineMode.set(false) + publication.suppressObviousFunctions.set(true) + publication.includes.from(project.files(), "packages.md", "extra.md") + + // Output directory for additional files + // Use this block when you want to change the output directory and include extra files + html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x")) + html.includes.from(project.layout.projectDirectory.file("README.md")) + } + } + } } ``` @@ -745,49 +713,41 @@ tasks.withType(DokkaTask.class) { -

The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.

-

If set for a single-project build or a MultiModule task, it is used as the project name.

+

+ The display name to refer to the project’s documentation. It appears in the table of contents, navigation, + headers, and log messages. In multi-project builds, each subproject moduleName is + used as its section title in aggregated documentation. +

Default: Gradle project name

- The module version. If set for a single-project build or a MultiModule task, it is used as the - project version. + The subproject version displayed in the generated documentation. + In single-project builds, it is used as the project version. + In multi-project builds, each subproject moduleVersion + is used when aggregating documentation.

Default: Gradle project version

 -

The directory to where documentation is generated, regardless of format. It can be set on a per-task basis.

-

- The default is {project}/{buildDir}/{format}, where {format} is the task name with - the "dokka" prefix removed. For the dokkaHtmlMultiModule task, it is - project/buildDir/htmlMultiModule. +

The directory where the generated documentation is stored.

+

This setting applies to all documentation formats (HTML, Javadoc, etc.) generated by the dokkaGenerate task.

+

Default: build/dokka/html

+

Output directory for additional files

+

You can specify the output directory and include additional files for both single and multi-project builds. + For multi-project builds, + set the output directory and include additional files (such as README.md) + in the configuration of the root project.

- Whether to fail documentation generation if Dokka has emitted a warning or an error. + Determines whether Dokka should fail the build when a warning occurs during documentation generation. The process waits until all errors and warnings have been emitted first.

This setting works well with reportUndocumented.

Default: false

 - -

Whether to suppress obvious functions.

-

- A function is considered to be obvious if it is:

- -
  • - Inherited from kotlin.Any, Kotlin.Enum, java.lang.Object or - java.lang.Enum, such as equals, hashCode, toString. -
    • -
  • - Synthetic (generated by the compiler) and does not have any documentation, such as - dataClass.componentN or dataClass.copy. -
    • -     -

    Default: true

    -

    Whether to suppress inherited members that aren't explicitly overridden in a given class.

    @@ -809,11 +769,36 @@ tasks.withType(DokkaTask.class) { but can also worsen documentation quality and user experience. For example, by not resolving class/member links from your dependencies, including the standard library.

    +

    Note: You can cache fetched files locally and provide them to Dokka as local paths. See + the externalDocumentationLinks section.

    +

    Default: false

    +     + +

    Whether to suppress obvious functions.

    +

    + A function is considered to be obvious if it is:

    + +
  • + Inherited from kotlin.Any, Kotlin.Enum, java.lang.Object or + java.lang.Enum, such as equals, hashCode, toString. +
    • +
  • + Synthetic (generated by the compiler) and does not have any documentation, such as + dataClass.componentN or dataClass.copy. +
    • +     +

    Default: true

    +     + +

    + A list of Markdown files that contain + subproject and package documentation. +

    +

    The contents of the specified files are parsed and embedded into documentation as subproject and package descriptions.

    - Note: You can cache fetched files locally and provide them to - Dokka as local paths. See externalDocumentationLinks section. + See Dokka gradle example + for an example of what it looks like and how to use it.

    -

    Default: false

         @@ -826,29 +811,25 @@ Dokka allows configuring some options for ```kotlin -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.Platform -import java.net.URL +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { +dokka { // .. - // general configuration section + // General configuration section // .. + // Source sets configuration dokkaSourceSets { - // configuration exclusive to the 'linux' source set + // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } + configureEach { suppress.set(false) displayName.set(name) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) reportUndocumented.set(false) skipEmptyPackages.set(true) skipDeprecated.set(false) @@ -856,24 +837,19 @@ tasks.withType().configureEach { jdkVersion.set(8) languageVersion.set("1.7") apiVersion.set("1.7") - noStdlibLink.set(false) - noJdkLink.set(false) - noAndroidSdkLink.set(false) - includes.from(project.files(), "packages.md", "extra.md") - platform.set(Platform.DEFAULT) sourceRoots.from(file("src")) classpath.from(project.files(), file("libs/dependency.jar")) samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") - + sourceLink { // Source link section } - externalDocumentationLink { - // External documentation link section - } perPackageOption { // Package options section } + externalDocumentationLinks { + // External documentation links section + } } } } @@ -953,13 +929,18 @@ tasks.withType(DokkaTask.class) {

    By default, the value is deduced from information provided by the Kotlin Gradle plugin.

    -

    The set of visibility modifiers that should be documented.

    +

    Defines which visibility modifiers Dokka should include in the generated documentation.

    - This can be used if you want to document protected/internal/private declarations, - as well as if you want to exclude public declarations and only document internal API. + Use them if you want to document Protected/Internal/Private declarations, + as well as if you want to exclude Public declarations and only document internal API.

    -

    This can be configured on per-package basis.

    -

    Default: DokkaConfiguration.Visibility.PUBLIC

    +

    + Additionally, you can use Dokka's + documentedVisibilities() function + to add documented visibilities. +

    +

    This can be configured on a per-package basis.

    +

    Default: VisibilityModifier.Public

    @@ -967,7 +948,7 @@ tasks.withType(DokkaTask.class) { after they have been filtered by documentedVisibilities and other filters.

    This setting works well with failOnWarning.

    -

    This can be configured on per-package basis.

    +

    This can be configured on a per-package basis.

    Default: false

     @@ -983,7 +964,7 @@ tasks.withType(DokkaTask.class) {

    Whether to document declarations annotated with @Deprecated.

    -

    This can be configured on per-package basis.

    +

    This can be configured on a per-package basis.

    Default: false

     @@ -1022,45 +1003,6 @@ tasks.withType(DokkaTask.class) {

    By default, it is deduced from languageVersion.

     - -

    - Whether to generate external documentation links that lead to the API reference - documentation of Kotlin's standard library. -

    -

    Note: Links are generated when noStdLibLink is set to false.

    -

    Default: false

    -     - -

    Whether to generate external documentation links to JDK's Javadocs.

    -

    The version of JDK Javadocs is determined by the jdkVersion option.

    -

    Note: Links are generated when noJdkLink is set to false.

    -

    Default: false

    -     - - -

    Whether to generate external documentation links to the Android SDK API reference.

    -

    This is only relevant in Android projects, ignored otherwise.

    -

    Note: Links are generated when noAndroidSdkLink is set to false.

    -

    Default: false

    -     - -

    - A list of Markdown files that contain - module and package documentation. -

    -

    The contents of the specified files are parsed and embedded into documentation as module and package descriptions.

    -

    - See Dokka gradle example - for an example of what it looks like and how to use it. -

    -     - -

    - The platform to be used for setting up code analysis and - @sample environment. -

    -

    The default value is deduced from information provided by the Kotlin Gradle plugin.

    -

    The source code roots to be analyzed and documented. @@ -1072,7 +1014,7 @@ tasks.withType(DokkaTask.class) {

    The classpath for analysis and interactive samples.

    This is useful if some types that come from dependencies are not resolved/picked up automatically.

    This option accepts both .jar and .klib files.

    -

    By default, classpath is deduced from information provided by the Kotlin Gradle plugin.

    +

    By default, the classpath is deduced from information provided by the Kotlin Gradle plugin.

    @@ -1084,8 +1026,13 @@ tasks.withType(DokkaTask.class) { ### Source link configuration +Configure source links +to allow navigation from the generated documentation to the corresponding source code in a remote repository. +Use the `dokkaSourceSets.main{}` block for this configuration. + The `sourceLinks` configuration block allows you to add a `source` link to each signature -that leads to the `remoteUrl` with a specific line number. (The line number is configurable by setting `remoteLineSuffix`). +that leads to the `remoteUrl` with a specific line number. +The line number is configurable by setting `remoteLineSuffix`. This helps readers to find the source code for each declaration. @@ -1093,35 +1040,53 @@ For an example, see the documentation for the [`count()`](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/count.html) function in `kotlinx.coroutines`. - - +The syntax of `build.gradle.kts` files differs from regular `.kt` +files (such as those used for custom Gradle plugins) because Gradle's Kotlin DSL uses type-safe accessors: + + + ```kotlin -import org.jetbrains.dokka.gradle.DokkaTask -import java.net.URL +// build.gradle.kts -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { - // .. - // general configuration section - // .. - - dokkaSourceSets.configureEach { - // .. - // source set configuration section - // .. - +dokka { + dokkaSourceSets.main { sourceLink { - localDirectory.set(projectDir.resolve("src")) - remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) + localDirectory.set(file("src/main/kotlin")) + remoteUrl("https://github.com/your-repo") remoteLineSuffix.set("#L") } } } ``` + + + +```kotlin +// CustomPlugin.kt + +import org.gradle.api.Plugin +import org.gradle.api.Project +import org.jetbrains.dokka.gradle.DokkaExtension + +abstract class CustomPlugin : Plugin { + override fun apply(project: Project) { + project.plugins.apply("org.jetbrains.dokka") + project.extensions.configure(DokkaExtension::class.java) { dokka -> + dokka.dokkaSourceSets.named("main") { dss -> + dss.includes.from("README.md") + dss.sourceLink { + it.localDirectory.set(project.file("src/main/kotlin")) + it.remoteUrl("https://example.com/src") + it.remoteLineSuffix.set("#L") + } + } + } + } +} +``` + @@ -1189,36 +1154,51 @@ tasks.withType(DokkaTask.class) { +Since the source link configuration has [changed](https://docs.gradle.org/current/userguide/upgrading_version_8.html#deprecated_invalid_url_decoding), +use the `URI` class to specify the remote URL: + +```kotlin +remoteUrl.set(URI("https://github.com/your-repo")) + +// or + +remoteUrl("https://github.com/your-repo") +``` + +Additionally, +you can use two [utility functions](https://github.com/Kotlin/dokka/blob/220922378e6c68eb148fda2ec80528a1b81478c9/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt#L82-L96) +for setting the URL: + +```kotlin +fun remoteUrl(@Language("http-url-reference") value: String): Unit = + remoteUrl.set(URI(value)) + +// and + +fun remoteUrl(value: Provider): Unit = + remoteUrl.set(value.map(::URI)) +``` + ### Package options -The `perPackageOption` configuration block allows setting some options for specific packages matched by `matchingRegex`. +The `perPackageOption` configuration block allows setting some options for specific packages matched by `matchingRegex`: ```kotlin -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { - // .. - // general configuration section - // .. - - dokkaSourceSets.configureEach { - // .. - // source set configuration section - // .. - - perPackageOption { - matchingRegex.set(".*api.*") - suppress.set(false) - skipDeprecated.set(false) - reportUndocumented.set(false) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) +dokka { + dokkaPublications.html { + dokkaSourceSets.configureEach { + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) + } } } } @@ -1269,7 +1249,7 @@ tasks.withType(DokkaTask.class) {

    Whether to document declarations annotated with @Deprecated.

    -

    This can be configured on source set level.

    +

    This can be configured on the source set level.

    Default: false

     @@ -1278,23 +1258,30 @@ tasks.withType(DokkaTask.class) { after they have been filtered by documentedVisibilities and other filters.

    This setting works well with failOnWarning.

    -

    This can be configured on source set level.

    +

    This can be configured on the source set level.

    Default: false

     -

    The set of visibility modifiers that should be documented.

    +

    Defines which visibility modifiers Dokka should include in the generated documentation.

    +

    + Use them if you want to document Protected/Internal/Private + declarations within this package, + as well as if you want to exclude Public declarations and only document internal API. +

    - This can be used if you want to document protected/internal/private declarations within this package, - as well as if you want to exclude public declarations and only document internal API. + Additionally, you can use Dokka's + documentedVisibilities() function + to add documented visibilities.

    -

    This can be configured on source set level.

    -

    Default: DokkaConfiguration.Visibility.PUBLIC

    +

    This can be configured on the source set level.

    +

    Default: VisibilityModifier.Public

     ### External documentation links configuration -The `externalDocumentationLink` block allows the creation of links that lead to the externally hosted documentation of +The `externalDocumentationLinks {}` +block allows the creation of links that lead to the externally hosted documentation of your dependencies. For example, if you are using types from `kotlinx.serialization`, by default they are unclickable in your @@ -1303,33 +1290,20 @@ is built by Dokka and is [published on kotlinlang.org](https://kotlinlang.org/ap configure external documentation links for it. Thus allowing Dokka to generate links for types from the library, making them resolve successfully and clickable. -By default, external documentation links for Kotlin standard library, JDK, Android SDK and AndroidX are configured. +By default, external documentation links for Kotlin standard library, JDK, Android SDK, and AndroidX are configured. + +Register external documentation links using the `register()` method to define each link. +The `externalDocumentationLinks` API uses this method aligning with Gradle DSL conventions: ```kotlin -import org.jetbrains.dokka.gradle.DokkaTask -import java.net.URL - -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { - // .. - // general configuration section - // .. - +dokka { dokkaSourceSets.configureEach { - // .. - // source set configuration section - // .. - - externalDocumentationLink { - url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/")) - packageListUrl.set( - rootProject.projectDir.resolve("serialization.package.list").toURL() - ) + externalDocumentationLinks.register("example-docs") { + url("https://example.com/docs/") + packageListUrl("https://example.com/docs/package-list") } } } @@ -1387,7 +1361,7 @@ tasks.withType(DokkaTask.class) {

    Package lists contain information about the documentation and the project itself, - such as module and package names. + such as subproject and package names.

    This can also be a locally cached file to avoid network calls.

    @@ -1395,38 +1369,41 @@ tasks.withType(DokkaTask.class) { ### Complete configuration -Below you can see all possible configuration options applied at the same time. +Below you can see all possible configuration options applied at the same time: ```kotlin -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.Platform -import java.net.URL +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { - moduleName.set(project.name) - moduleVersion.set(project.version.toString()) - outputDirectory.set(layout.buildDirectory.dir("dokka/$name")) - failOnWarning.set(false) - suppressObviousFunctions.set(true) - suppressInheritedMembers.set(false) - offlineMode.set(false) +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +dokka { + dokkaPublications.html { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(layout.buildDirectory.dir("dokka/html")) + failOnWarning.set(false) + suppressInheritedMembers.set(false) + offlineMode.set(false) + suppressObviousFunctions.set(true) + includes.from(project.files(), "packages.md", "extra.md") + } dokkaSourceSets { + // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } + configureEach { suppress.set(false) displayName.set(name) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) reportUndocumented.set(false) skipEmptyPackages.set(true) skipDeprecated.set(false) @@ -1434,26 +1411,19 @@ tasks.withType().configureEach { jdkVersion.set(8) languageVersion.set("1.7") apiVersion.set("1.7") - noStdlibLink.set(false) - noJdkLink.set(false) - noAndroidSdkLink.set(false) - includes.from(project.files(), "packages.md", "extra.md") - platform.set(Platform.DEFAULT) sourceRoots.from(file("src")) classpath.from(project.files(), file("libs/dependency.jar")) samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") - + sourceLink { - localDirectory.set(projectDir.resolve("src")) - remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) + localDirectory.set(file("src/main/kotlin")) + remoteUrl("https://example.com/src") remoteLineSuffix.set("#L") } - externalDocumentationLink { - url.set(URL("https://kotlinlang.org/api/core/kotlin-stdlib/")) - packageListUrl.set( - rootProject.projectDir.resolve("stdlib.package.list").toURL() - ) + externalDocumentationLinks { + url = URL("https://example.com/docs/") + packageListUrl = File("/path/to/package-list").toURI().toURL() } perPackageOption { @@ -1463,11 +1433,11 @@ tasks.withType().configureEach { reportUndocumented.set(false) documentedVisibilities.set( setOf( - Visibility.PUBLIC, - Visibility.PRIVATE, - Visibility.PROTECTED, - Visibility.INTERNAL, - Visibility.PACKAGE + VisibilityModifier.Public, + VisibilityModifier.Private, + VisibilityModifier.Protected, + VisibilityModifier.Internal, + VisibilityModifier.Package ) ) } @@ -1499,7 +1469,7 @@ tasks.withType(DokkaTask.class) { dokkaSourceSets { named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } configureEach {