From 03c2574138df09ffbce032cd256284a46d6a7dc3 Mon Sep 17 00:00:00 2001 From: alepedroza <39709865+AlejandraPedroza@users.noreply.github.com> Date: Mon, 17 Nov 2025 13:49:08 -0600 Subject: [PATCH 1/2] Dokka Gradle plugin doc update This PR updates all the documents relevant to Dokka Gradle plugin v2 # Conflicts: # docs/topics/dokka-get-started.md # docs/topics/dokka-plugins.md # docs/topics/formats/dokka-html.md # docs/topics/formats/dokka-markdown.md --- docs/dokka.tree | 3 +- docs/labels.list | 18 + docs/topics/dokka-get-started.md | 50 +- .../topics/dokka-gradle-troubleshooting-md.md | 71 ++ docs/topics/dokka-migration.md | 74 +- docs/topics/dokka-plugins.md | 97 +- docs/topics/formats/dokka-html.md | 91 +- docs/topics/formats/dokka-javadoc.md | 28 +- docs/topics/formats/dokka-markdown.md | 121 +- docs/topics/runners/dokka-gradle.md | 1100 +++++++++-------- 10 files changed, 851 insertions(+), 802 deletions(-) create mode 100644 docs/labels.list create mode 100644 docs/topics/dokka-gradle-troubleshooting-md.md 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..a5d3d45b17 100644 --- a/docs/topics/dokka-get-started.md +++ b/docs/topics/dokka-get-started.md @@ -5,18 +5,9 @@ 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). -> -{style="note"} +**Apply the Gradle Dokka plugin** -Apply the Gradle plugin for Dokka in the root build script of your project: +Apply the Dokka Gradle plugin (DGP) in the root build script of your project: ```kotlin plugins { @@ -24,21 +15,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-module projects** -```kotlin -subprojects { - apply(plugin = "org.jetbrains.dokka") -} +When documenting [multi-module projects (multi-project builds)](https://docs.gradle.org/current/userguide/multi_project_builds.html), +you don't need to apply the plugin to every module or subproject you want to document. Instead, share Dokka configuration across modules +by using one of the following approaches: + +* Convention plugin +* Direct configuration in each module if you’re not using convention plugins + +For more information about sharing Dokka configuration in multi-module projects, +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-module projects. +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-module and single-module projects, +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 +73,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..4bb3b3e9ce 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. @@ -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-plugins.md b/docs/topics/dokka-plugins.md index 8fe048d7c5..a0ebf6c9c0 100644 --- a/docs/topics/dokka-plugins.md +++ b/docs/topics/dokka-plugins.md @@ -13,11 +13,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 +30,25 @@ 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 unified under the `dokka {}` DSL: ```kotlin -dependencies { - // Is applied universally - dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%") +plugins { + id("org.jetbrains.dokka") version "2.0.0" +} - // Is applied for the single-module dokkaHtml task only - dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +dokka { + dependencies { + dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:2.0.0") + } - // Is applied for HTML format in multi-project builds - dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") } ``` -> 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 modules](dokka-gradle.md#multi-project-configuration). +> {style="note"} @@ -79,7 +70,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 +131,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 `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/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. @@ -281,7 +248,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..0c23735328 100644 --- a/docs/topics/formats/dokka-html.md +++ b/docs/topics/formats/dokka-html.md @@ -1,7 +1,6 @@ [//]: # (title: HTML) -HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release. - +HTML is Dokka's default and recommended output format. You can see an example of the output by browsing documentation for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). @@ -10,14 +9,9 @@ for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). 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: + * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. + * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). * 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 +26,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 +131,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 +171,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). @@ -252,7 +218,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 +239,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} ``` diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md index a7f42c463e..a458408715 100644 --- a/docs/topics/formats/dokka-javadoc.md +++ b/docs/topics/formats/dokka-javadoc.md @@ -1,10 +1,5 @@ [//]: # (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.** -> -{style="warning"} + 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,14 +7,15 @@ 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 @@ -34,12 +30,18 @@ It is open source and you can find the source code on [GitHub](https://github.co -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 "2.0.0" +} +``` -| **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. | +Once you applied the plugin, you can run the following tasks: +* `dokkaGeneratePublicationJavadoc` to generate documentation only in Javadoc format. +* `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-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..428c22b894 100644 --- a/docs/topics/formats/dokka-markdown.md +++ b/docs/topics/formats/dokka-markdown.md @@ -1,11 +1,5 @@ [//]: # (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.** -> -> 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"} + Dokka is able to generate documentation in [GitHub Flavored](#gfm) and [Jekyll](#jekyll) compatible Markdown. @@ -23,18 +17,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: +* `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 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 +106,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 +137,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 +144,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 +210,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..b8302e6a90 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -15,17 +15,19 @@ 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 +50,115 @@ 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-module projects (multi-project builds), you don't need to apply the plugin explicitly to every +module or subproject you want to document. +Instead, +Dokka expects you to share configuration across modules using convention plugins or manual configuration per module. +For more information, see +how to configure [single-module projects](#single-project-configuration) and [multi-module projects](#multi-project-configuration). + +> * 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"} - - +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). -```kotlin -subprojects { - apply(plugin = "org.jetbrains.dokka") -} -``` +## Generate documentation - - +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. -```groovy -subprojects { - apply plugin: 'org.jetbrains.dokka' -} +Use the following Gradle task to generate documentation: + +```shell +./gradlew :dokkaGenerate ``` - - +The key behavior of the `dokkaGenerate` Gradle task is: -See [Configuration examples](#configuration-examples) if you are not sure where to apply Dokka. +* This task generates documentation for both [single](#single-project-configuration) + and [multi-module](#multi-project-configuration) projects. +* 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 multi-module and single-module projects. + You can [change the location (`outputDirectory`)](#general-configuration). -> 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"} +### Configure documentation output 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. +> 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"} -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. - -## Generate documentation - -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. - -### Single-project builds - -Use the following tasks to build documentation for simple, single-project applications and libraries: +You can choose to generate the API documentation in HTML, Javadoc, +or both formats at the same time: -| **Task** | **Description** | -|-------------|----------------------------------------------------------| -| `dokkaHtml` | Generates documentation in [HTML](dokka-html.md) format. | +1. Place the corresponding plugin `id` in the `plugins {}` block of your project's `build.gradle.kts` file: -#### Experimental formats + ```kotlin + plugins { + // Generates HTML documentation + id("org.jetbrains.dokka") version "2.0.0" -| **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. | + // Generates Javadoc documentation + id("org.jetbrains.dokka-javadoc") version "2.0.0" -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). + // Keeping both plugin IDs generates both formats + } + ``` -### Multi-project builds +2. Run the corresponding Gradle task. -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. + Here is a list of the plugin `id` and Gradle task that correspond to each format: -#### MultiModule tasks + | | **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` | -`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. + > 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"} -Dokka creates the following tasks for **parent** projects automatically: +The Markdown output format (including GFM and Jekyll) is not supported by default, +but you can [enable it manually](dokka-markdown.md). -| **Task** | **Description** | -|------------------------|------------------------------------------------------------------------------| -| `dokkaHtmlMultiModule` | Generates multi-module documentation in [HTML](dokka-html.md) output format. | +### Aggregate documentation output in multi-module projects -#### Experimental formats (multi-module) +Dokka can aggregate documentation from multiple modules (subprojects) into a single output or publication. -| **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. | - -> 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-modules) to +all documentable modules 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 modules, add the `dependencies {}` +block in the `build.gradle.kts` file of the root project: -#### MultiModule results +```kotlin +dependencies { + dokka(project(":some-subproject:")) + dokka(project(":another-subproject:")) +} +``` -Given a project with the following structure: +Given a project with the following structure: ```text . @@ -164,70 +171,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-module 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 modules, each module has its own subdirectory within the aggregated documentation. +DGP ensures each module 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 module or 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 module 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 module directory + modulePath.set("maths") +} +``` ## Build javadoc.jar @@ -245,15 +222,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") } ``` @@ -291,15 +270,16 @@ Depending on the type of project that you have, the way you apply and configure [configuration options](#configuration-options) themselves are the same, regardless of the type of your project. For simple and flat projects with a single `build.gradle.kts` or `build.gradle` file found in the root of your project, -see [Single-project configuration](#single-project-configuration). +see [Single-project configuration (single-module projects)](#single-project-configuration). For a more complex build with subprojects and multiple nested `build.gradle.kts` or `build.gradle` files, -see [Multi-project configuration](#multi-project-configuration). +see [Multi-project configuration (multi-module projects)](#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-module projects or 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 +346,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 +395,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-module projects or 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 +452,236 @@ typically have the following structure: -In this case, there are multiple ways of applying and configuring Dokka. +Single and multi-module documentation share the same +[configuration model using the top-level `dokka {}` DSL](#single-project-configuration). +In multi-module projects, +you configure Dokka in the root project and can optionally share settings across subprojects or modules. -#### Subproject configuration +To share Dokka configuration across modules, you can use either: -To configure subprojects in a multi-project build, you need to configure [`Partial`](#partial-tasks) tasks. +* [Direct configuration in multi-module projects without convention plugins](#direct-configuration-in-multi-module-projects-without-convention-plugins) +* [Convention plugins](#multi-module-projects-with-convention-plugins) -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: +After sharing Dokka configuration, you can aggregate the documentation from multiple modules into a single output. +For more information, see +[Aggregate documentation output in multi-module projects](#aggregate-documentation-output-in-multi-module-projects). - - - -In the root `./build.gradle.kts`: - -```kotlin -import org.jetbrains.dokka.gradle.DokkaTaskPartial +> For a multi-module 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-module projects without 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 module. +This involves manually setting up the shared configuration in each module'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-module project 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: - - + ```kotlin + plugins { + id("org.jetbrains.dokka") + } -Inside `./subproject-A/build.gradle.kts`: + dokka { + // The shared configuration goes here + } + ``` -```kotlin -apply(plugin = "org.jetbrains.dokka") + You need to add the shared Dokka [configuration](#configuration-options) common to all modules 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. -// configuration for subproject-A only. -tasks.dokkaHtmlPartial { - outputDirectory.set(layout.buildDirectory.dir("docs/partial")) -} -``` +##### Apply the convention plugin to your modules - - +Apply the Dokka convention plugin across your modules (subprojects) by adding it to each module's `build.gradle.kts` +file: -Inside `./subproject-A/build.gradle`: - -```groovy -apply plugin: 'org.jetbrains.dokka' - -// configuration for subproject-A only. -dokkaHtmlPartial { - outputDirectory.set(file("build/docs/partial")) +```kotlin +plugins { + id("dokka-convention") } ``` - - +#### Multi-module projects with convention plugins -#### Parent project configuration - -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. +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). -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: +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). - - +#### Parent project configuration -In the root `./build.gradle.kts` file: +In multi-module projects, you can configure settings that apply to the entire documentation in the root project. +This can include defining the output format, output directory, documentation module name, +aggregating documentation from all +modules, 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(":subproject-A")) + dokka(project(":subproject-B")) +} +``` -In the root `./build.gradle` file: +Additionally, each module can have its own `dokka {}` block if it needs custom configuration. +In the following example, the subproject module applies the Dokka plugin, sets a custom module 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("Subproject 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 +714,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-module projects, each module or subproject’s 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 module version displayed in the generated documentation. + In single-module projects, it is used as the project version. + In multi-module projects, each module or subproject’s 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-module and multi-module projects. + For multi-module projects, + 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 +770,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.

    - Note: You can cache fetched files locally and provide them to - Dokka as local paths. See externalDocumentationLinks section. + 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 + 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.

    -

    Default: false

         @@ -826,29 +812,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") 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) @@ -859,21 +841,20 @@ tasks.withType().configureEach { 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 { + // Package options section + } } } } @@ -953,13 +934,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.

    +

    + 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 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. + Additionally, you can use Dokka's + documentedVisibilities() function + to add documented visibilities.

    -

    This can be configured on per-package basis.

    -

    Default: DokkaConfiguration.Visibility.PUBLIC

    +

    This can be configured on a per-package basis.

    +

    Default: VisibilityModifier.Public

    @@ -967,7 +953,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 +969,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

     @@ -1043,17 +1029,6 @@ tasks.withType(DokkaTask.class) {

    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 @@ -1072,7 +1047,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 +1059,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 +1073,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 +1187,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 +1282,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 +1291,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 +1323,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") } } } @@ -1395,82 +1402,82 @@ 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 "2.0.0" +} - dokkaSourceSets { - named("linux") { - dependsOn("native") - sourceRoots.from(file("linux/src")) +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") + sourceRoots.from(file("linux/src")) + } + + configureEach { + suppress.set(false) + displayName.set(name) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) + reportUndocumented.set(false) + skipEmptyPackages.set(true) + skipDeprecated.set(false) + suppressGeneratedFiles.set(true) + jdkVersion.set(8) + languageVersion.set("1.7") + apiVersion.set("1.7") + noStdlibLink.set(false) + noJdkLink.set(false) + noAndroidSdkLink.set(false) + 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(file("src/main/kotlin")) + remoteUrl("https://example.com/src") + remoteLineSuffix.set("#L") } - configureEach { - suppress.set(false) - displayName.set(name) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) - reportUndocumented.set(false) - skipEmptyPackages.set(true) - skipDeprecated.set(false) - suppressGeneratedFiles.set(true) - 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")) - remoteLineSuffix.set("#L") - } - externalDocumentationLink { - url.set(URL("https://kotlinlang.org/api/core/kotlin-stdlib/")) - packageListUrl.set( - rootProject.projectDir.resolve("stdlib.package.list").toURL() - ) - } + externalDocumentationLink { + url = URL("https://example.com/docs/") + packageListUrl = File("/path/to/package-list").toURI().toURL() + } - perPackageOption { - matchingRegex.set(".*api.*") - suppress.set(false) - skipDeprecated.set(false) - reportUndocumented.set(false) - documentedVisibilities.set( - setOf( - Visibility.PUBLIC, - Visibility.PRIVATE, - Visibility.PROTECTED, - Visibility.INTERNAL, - Visibility.PACKAGE - ) + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set( + setOf( + VisibilityModifier.Public, + VisibilityModifier.Private, + VisibilityModifier.Protected, + VisibilityModifier.Internal, + VisibilityModifier.Package ) - } + ) } } } @@ -1549,3 +1556,10 @@ tasks.withType(DokkaTask.class) { + +## Enable build cache and configuration cache + +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 ). From dbfcbe15af6325d0ab37de529ef120cb03e34841 Mon Sep 17 00:00:00 2001 From: alepedroza <39709865+AlejandraPedroza@users.noreply.github.com> Date: Wed, 19 Nov 2025 16:48:24 -0600 Subject: [PATCH 2/2] Developer's reviews --- docs/topics/dokka-get-started.md | 19 +- docs/topics/dokka-migration.md | 34 +-- docs/topics/dokka-module-and-package-docs.md | 16 +- docs/topics/dokka-plugins.md | 22 +- docs/topics/formats/dokka-html.md | 29 +- docs/topics/formats/dokka-javadoc.md | 17 +- docs/topics/formats/dokka-markdown.md | 8 +- docs/topics/runners/dokka-gradle.md | 276 ++++++++----------- 8 files changed, 205 insertions(+), 216 deletions(-) diff --git a/docs/topics/dokka-get-started.md b/docs/topics/dokka-get-started.md index a5d3d45b17..6edc9c29f4 100644 --- a/docs/topics/dokka-get-started.md +++ b/docs/topics/dokka-get-started.md @@ -5,6 +5,11 @@ Below you can find simple instructions to help you get started with Dokka. +> 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 Dokka plugin** Apply the Dokka Gradle plugin (DGP) in the root build script of your project: @@ -15,16 +20,16 @@ plugins { } ``` -**Document multi-module projects** +**Document multi-project builds** -When documenting [multi-module projects (multi-project builds)](https://docs.gradle.org/current/userguide/multi_project_builds.html), -you don't need to apply the plugin to every module or subproject you want to document. Instead, share Dokka configuration across modules +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 module if you’re not using convention plugins +* Direct configuration in each subproject if you’re not using convention plugins -For more information about sharing Dokka configuration in multi-module projects, +For more information about sharing Dokka configuration in multi-project builds, see [Multi-project configuration](dokka-gradle.md#multi-project-configuration). **Generate documentation** @@ -35,13 +40,13 @@ To generate documentation, run the following Gradle task: ./gradlew :dokkaGenerate ``` -This task works for both single and multi-module projects. +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). **Set output directory** -By default, the output directory is set to `/build/dokka/html` for both multi-module and single-module projects, +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). diff --git a/docs/topics/dokka-migration.md b/docs/topics/dokka-migration.md index 4bb3b3e9ce..1d23fdb3f1 100644 --- a/docs/topics/dokka-migration.md +++ b/docs/topics/dokka-migration.md @@ -43,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%" } ``` @@ -525,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). @@ -542,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 @@ -599,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 { @@ -614,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. @@ -646,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 @@ -676,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 @@ -687,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") } ``` @@ -733,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 } 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 a0ebf6c9c0..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. @@ -30,24 +35,21 @@ to your project: -The way to apply Dokka plugins is unified under the `dokka {}` DSL: +The way to apply Dokka plugins is: ```kotlin plugins { - id("org.jetbrains.dokka") version "2.0.0" + id("org.jetbrains.dokka") version "%dokkaVersion%" } -dokka { - dependencies { - dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:2.0.0") - } - +dependencies { + dokkaPlugin("org.jetbrains.dokka:mathjax-plugin") } ``` > * 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 modules](dokka-gradle.md#multi-project-configuration). +> * 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"} @@ -138,7 +140,7 @@ custom style sheets (`customStyleSheets` option), and a modified footer message -To configure Dokka plugins in a type-safe way, use the `pluginsConfiguration{}` block: +To configure Dokka plugins in a type-safe way, use the `dokka.pluginsConfiguration {}` block: ```kotlin dokka { @@ -155,7 +157,7 @@ For an example of Dokka plugins configuration, see the Dokka 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). +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. diff --git a/docs/topics/formats/dokka-html.md b/docs/topics/formats/dokka-html.md index 0c23735328..eb4079b153 100644 --- a/docs/topics/formats/dokka-html.md +++ b/docs/topics/formats/dokka-html.md @@ -1,8 +1,21 @@ [//]: # (title: HTML) -HTML is Dokka's default and recommended output format. -You can see an example of the output by browsing documentation -for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). +> 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. + +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 @@ -10,8 +23,12 @@ HTML as an output format is supported by all runners. To generate HTML documenta your build tool or runner: * For [Gradle](dokka-gradle.md#generate-documentation), run the following tasks: - * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. * `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. @@ -206,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: @@ -255,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 a458408715..21d1e7b9b9 100644 --- a/docs/topics/formats/dokka-javadoc.md +++ b/docs/topics/formats/dokka-javadoc.md @@ -1,6 +1,11 @@ [//]: # (title: Javadoc) +> 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'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). @@ -19,12 +24,9 @@ and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tre ## 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 multiplatform projects. +> The Javadoc format does not support multi-project builds or Kotlin Multiplatform projects. > -{style="warning"} +{style="tip"} @@ -35,13 +37,14 @@ You need to apply the corresponding plugin id in the `plugins {}` block of your ```kotlin plugins { - id("org.jetbrains.dokka-javadoc") version "2.0.0" + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" } ``` Once you applied the plugin, you can run the following tasks: -* `dokkaGeneratePublicationJavadoc` to generate documentation only in Javadoc format. + * `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 428c22b894..1e195f4f5d 100644 --- a/docs/topics/formats/dokka-markdown.md +++ b/docs/topics/formats/dokka-markdown.md @@ -1,6 +1,12 @@ [//]: # (title: Markdown) +> 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 is able to generate documentation in [GitHub Flavored](#gfm) and [Jekyll](#jekyll) compatible Markdown. These formats give you more freedom in terms of hosting documentation as the output can be embedded right into your @@ -72,8 +78,8 @@ apply() ``` 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). +* `dokkaGenerateMarkdown` to generate documentation only in Markdown format. diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md index b8302e6a90..6ad94b420c 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -1,17 +1,10 @@ [//]: # (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). @@ -50,12 +43,11 @@ plugins { -When documenting multi-module projects (multi-project builds), you don't need to apply the plugin explicitly to every -module or subproject you want to document. +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 modules using convention plugins or manual configuration per module. +Dokka expects you to share configuration across subprojects using convention plugins or manual configuration per subproject. For more information, see -how to configure [single-module projects](#single-project-configuration) and [multi-module projects](#multi-project-configuration). +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) @@ -73,6 +65,13 @@ how to configure [single-module projects](#single-project-configuration) and [mu 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 + +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 ). + ## Generate documentation The Dokka Gradle plugin comes with [HTML](dokka-html.md) and [Javadoc](dokka-javadoc.md) output formats @@ -88,12 +87,12 @@ Use the following Gradle task to generate documentation: The key behavior of the `dokkaGenerate` Gradle task is: * This task generates documentation for both [single](#single-project-configuration) - and [multi-module](#multi-project-configuration) projects. + 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 multi-module and single-module projects. + directory for both single and multi-project builds. You can [change the location (`outputDirectory`)](#general-configuration). ### Configure documentation output format @@ -113,10 +112,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 } @@ -141,20 +140,20 @@ or both formats at the same time: The Markdown output format (including GFM and Jekyll) is not supported by default, but you can [enable it manually](dokka-markdown.md). -### Aggregate documentation output in multi-module projects +### Aggregate documentation output in multi-project builds -Dokka can aggregate documentation from multiple modules (subprojects) into a single output or publication. +Dokka can aggregate documentation from multiple subprojects into a single output or publication. -You have to [apply the Dokka plugin](#apply-the-convention-plugin-to-your-modules) to -all documentable modules before aggregating the documentation. +You have to [apply the Dokka plugin](#apply-the-convention-plugin-to-your-subprojects) to +all documentable subprojects before aggregating the documentation. -To aggregate documentation from multiple modules, add the `dependencies {}` +To aggregate documentation from multiple subprojects, add the `dependencies {}` block in the `build.gradle.kts` file of the root project: ```kotlin dependencies { - dokka(project(":some-subproject:")) - dokka(project(":another-subproject:")) + dokka(project(":childProjectA:")) + dokka(project(":childProjectB:")) } ``` @@ -175,22 +174,22 @@ 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/2.0.0/examples/gradle-v2/multimodule-example) +See our [multi-project example](https://github.com/Kotlin/dokka/tree/2.0.0/examples/gradle-v2/multimodule-example) for more details. #### Directory of aggregated documentation -When DGP aggregates modules, each module has its own subdirectory within the aggregated documentation. -DGP ensures each module has a unique directory by retaining the full project structure. +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. -For example, given a project with an aggregation in `:turbo-lib` and a nested module or subproject `:turbo-lib:maths`, +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 turbo-lib/build/dokka/html/turbo-lib/maths/ ``` -You can revert this behavior by manually specifying the module directory. +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 @@ -201,7 +200,7 @@ plugins { } dokka { - // Overrides the module directory + // Overrides the subproject directory modulePath.set("maths") } ``` @@ -270,14 +269,14 @@ Depending on the type of project that you have, the way you apply and configure [configuration options](#configuration-options) themselves are the same, regardless of the type of your project. For simple and flat projects with a single `build.gradle.kts` or `build.gradle` file found in the root of your project, -see [Single-project configuration (single-module projects)](#single-project-configuration). +see [Single-project configuration](#single-project-configuration). For a more complex build with subprojects and multiple nested `build.gradle.kts` or `build.gradle` files, -see [Multi-project configuration (multi-module projects)](#multi-project-configuration). +see [Multi-project configuration](#multi-project-configuration). ### Single-project configuration -Single-module projects or single-project builds usually have only one `build.gradle.kts` +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: @@ -403,7 +402,7 @@ For more information, see [Configuration options](#configuration-options). ### Multi-project configuration -[Multi-module projects or multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html) +[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: @@ -452,32 +451,32 @@ nested `build.gradle.kts` files and have a structure similar to the following: -Single and multi-module documentation share the same +Single and multi-project documentation share the same [configuration model using the top-level `dokka {}` DSL](#single-project-configuration). -In multi-module projects, -you configure Dokka in the root project and can optionally share settings across subprojects or modules. +In multi-project builds, +you configure Dokka in the root project and can optionally share settings across subprojects. -To share Dokka configuration across modules, you can use either: +To share Dokka configuration across subprojects, you can use either: -* [Direct configuration in multi-module projects without convention plugins](#direct-configuration-in-multi-module-projects-without-convention-plugins) -* [Convention plugins](#multi-module-projects-with-convention-plugins) +* [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) -After sharing Dokka configuration, you can aggregate the documentation from multiple modules into a single output. +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-module projects](#aggregate-documentation-output-in-multi-module-projects). +[Aggregate documentation output in multi-project-builds](#aggregate-documentation-output-in-multi-project-builds). -> For a multi-module project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example). +> For a multi-project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example). > {style="tip"} -#### Direct configuration in multi-module projects without convention plugins +#### Direct configuration in multi-project builds requiring convention plugins -If your project doesn't use convention plugins, you can share Dokka configurations by directly configuring each module. -This involves manually setting up the shared configuration in each module's `build.gradle.kts` file. +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. -Follow the next steps to configure your multi-module project without convention plugins. +Follow the next steps to configure your multi-project builds without convention plugins. ##### Set up the buildSrc directory @@ -526,14 +525,14 @@ After setting up the `buildSrc` directory, set up the Dokka convention plugin: } ``` - You need to add the shared Dokka [configuration](#configuration-options) common to all modules within the `dokka {}` + 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 modules +##### Apply the convention plugin to your subprojects -Apply the Dokka convention plugin across your modules (subprojects) by adding it to each module's `build.gradle.kts` +Apply the Dokka convention plugin across your subprojects by adding it to each subproject's `build.gradle.kts` file: ```kotlin @@ -542,20 +541,20 @@ plugins { } ``` -#### Multi-module projects with convention plugins +#### Multi-project builds with convention 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). #### Parent project configuration -In multi-module projects, you can configure settings that apply to the entire documentation in the root project. -This can include defining the output format, output directory, documentation module name, -aggregating documentation from all -modules, and other [configuration options](#configuration-options): +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 { @@ -577,13 +576,13 @@ dokka { // Aggregates subproject documentation dependencies { - dokka(project(":subproject-A")) - dokka(project(":subproject-B")) + dokka(project(":childProjectA")) + dokka(project(":childProjectB")) } ``` -Additionally, each module can have its own `dokka {}` block if it needs custom configuration. -In the following example, the subproject module applies the Dokka plugin, sets a custom module name, +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: ```kotlin @@ -594,7 +593,7 @@ plugins { dokka { dokkaPublications.html { - moduleName.set("Subproject A") + moduleName.set("Child Project A") includes.from("README.md") } } @@ -716,16 +715,16 @@ tasks.withType(DokkaTask.class) {

    The display name to refer to the project’s documentation. It appears in the table of contents, navigation, - headers, and log messages. In multi-module projects, each module or subproject’s moduleName is + 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 displayed in the generated documentation. - In single-module projects, it is used as the project version. - In multi-module projects, each module or subproject’s moduleVersion + 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

    @@ -735,8 +734,8 @@ tasks.withType(DokkaTask.class) {

    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-module and multi-module projects. - For multi-module projects, +

    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.

    @@ -793,9 +792,9 @@ tasks.withType(DokkaTask.class) {

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

    -

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

    +

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

    See Dokka gradle example for an example of what it looks like and how to use it. @@ -823,7 +822,7 @@ dokka { dokkaSourceSets { // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } @@ -838,10 +837,6 @@ dokka { jdkVersion.set(8) languageVersion.set("1.7") apiVersion.set("1.7") - noStdlibLink.set(false) - noJdkLink.set(false) - noAndroidSdkLink.set(false) - 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") @@ -853,7 +848,7 @@ dokka { // Package options section } externalDocumentationLinks { - // Package options section + // External documentation links section } } } @@ -1008,34 +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

    -     - -

    - 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. @@ -1394,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.

     @@ -1411,7 +1378,7 @@ Below you can see all possible configuration options applied at the same time: import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier plugins { - id("org.jetbrains.dokka") version "2.0.0" + id("org.jetbrains.dokka") version "%dokkaVersion%" } dokka { @@ -1425,59 +1392,55 @@ dokka { suppressObviousFunctions.set(true) includes.from(project.files(), "packages.md", "extra.md") } -} - -dokkaSourceSets { - // Example: Configuration exclusive to the 'linux' source set - named("linux") { - dependsOn("native") - sourceRoots.from(file("linux/src")) - } - configureEach { - suppress.set(false) - displayName.set(name) - documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) - reportUndocumented.set(false) - skipEmptyPackages.set(true) - skipDeprecated.set(false) - suppressGeneratedFiles.set(true) - jdkVersion.set(8) - languageVersion.set("1.7") - apiVersion.set("1.7") - noStdlibLink.set(false) - noJdkLink.set(false) - noAndroidSdkLink.set(false) - 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(file("src/main/kotlin")) - remoteUrl("https://example.com/src") - remoteLineSuffix.set("#L") - } - - externalDocumentationLink { - url = URL("https://example.com/docs/") - packageListUrl = File("/path/to/package-list").toURI().toURL() + dokkaSourceSets { + // Example: Configuration exclusive to the 'linux' source set + named("linux") { + dependentSourceSets{named("native")} + sourceRoots.from(file("linux/src")) } - perPackageOption { - matchingRegex.set(".*api.*") + configureEach { suppress.set(false) - skipDeprecated.set(false) + displayName.set(name) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) reportUndocumented.set(false) - documentedVisibilities.set( - setOf( - VisibilityModifier.Public, - VisibilityModifier.Private, - VisibilityModifier.Protected, - VisibilityModifier.Internal, - VisibilityModifier.Package + skipEmptyPackages.set(true) + skipDeprecated.set(false) + suppressGeneratedFiles.set(true) + jdkVersion.set(8) + languageVersion.set("1.7") + apiVersion.set("1.7") + 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(file("src/main/kotlin")) + remoteUrl("https://example.com/src") + remoteLineSuffix.set("#L") + } + + externalDocumentationLinks { + url = URL("https://example.com/docs/") + packageListUrl = File("/path/to/package-list").toURI().toURL() + } + + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set( + setOf( + VisibilityModifier.Public, + VisibilityModifier.Private, + VisibilityModifier.Protected, + VisibilityModifier.Internal, + VisibilityModifier.Package + ) ) - ) + } } } } @@ -1506,7 +1469,7 @@ tasks.withType(DokkaTask.class) { dokkaSourceSets { named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } configureEach { @@ -1556,10 +1519,3 @@ tasks.withType(DokkaTask.class) {     - -## Enable build cache and configuration cache - -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 ).