diff --git a/docs/dokka.tree b/docs/dokka.tree index 49a8b4bbce..4f8b9cdf22 100644 --- a/docs/dokka.tree +++ b/docs/dokka.tree @@ -6,13 +6,13 @@ + - 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..408423cace 100644 --- a/docs/topics/dokka-get-started.md +++ b/docs/topics/dokka-get-started.md @@ -5,18 +5,14 @@ Below you can find simple instructions to help you get started with Dokka. -> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, several configuration options, Gradle tasks, and steps to generate your documentation have been updated, including: -> -> * [Adjust configuration options](dokka-migration.md#adjust-configuration-options) -> * [Work with multi-module projects](dokka-migration.md#share-dokka-configuration-across-modules) -> * [Generate documentation with the updated tasks](dokka-migration.md#generate-documentation-with-the-updated-task) -> * [Specify an output directory](dokka-migration.md#output-directory) -> -> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). +> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. +> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md). > {style="note"} -Apply the Gradle plugin for Dokka in the root build script of your project: +**Apply the Gradle Dokka plugin** + +Apply the Dokka Gradle plugin (DGP) in the root build script of your project: ```kotlin plugins { @@ -24,27 +20,47 @@ plugins { } ``` -When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need -to apply the Gradle plugin within subprojects as well: +**Document multi-project builds** -```kotlin -subprojects { - apply(plugin = "org.jetbrains.dokka") -} +When documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), +you need to apply the plugin to every subproject you want to document. Share Dokka configuration across subprojects +by using one of the following approaches: + +* Convention plugin +* Direct configuration in each subproject if you’re not using convention plugins + +For more information about sharing Dokka configuration in multi-project builds, +see [Multi-project configuration](dokka-gradle.md#multi-project-configuration). + +**Generate documentation** + +To generate documentation, run the following Gradle task: + +```Bash +./gradlew :dokkaGenerate ``` -To generate documentation, run the following Gradle tasks: +This task works for both single and multi-project builds. +You can use different tasks to generate output in [HTML](dokka-html.md), +[Javadoc](dokka-javadoc.md) or both [HTML and Javadoc](dokka-gradle.md#configure-documentation-output-format). -* `dokkaHtml` for single-project builds -* `dokkaHtmlMultiModule` for multi-project builds +**Set output directory** -By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. +By default, the output directory is set to `/build/dokka/html` for both multi-project and single-project builds, +but you can [configure it](dokka-gradle.md#general-configuration). To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md). +> 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 Gradle plugin for Dokka in the root build script of your project: ```groovy @@ -53,21 +69,34 @@ plugins { } ``` -When documenting [multi-project](https://docs.gradle.org/current/userguide/multi_project_builds.html) builds, you need -to apply the Gradle plugin within subprojects as well: +**Document multi-project builds** -```groovy -subprojects { - apply plugin: 'org.jetbrains.dokka' -} +When documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), +you need to apply the plugin to every subproject you want to document. Share Dokka configuration across subprojects +by using one of the following approaches: + +* Convention plugin +* Direct configuration in each subproject if you’re not using convention plugins + +For more information about sharing Dokka configuration in multi-project builds, +see [Multi-project configuration](dokka-gradle.md#multi-project-configuration). + +**Generate documentation** + +To generate documentation, run the following Gradle task: + +```Bash +./gradlew :dokkaGenerate ``` -To generate documentation, run the following Gradle tasks: +This task works for both single and multi-project builds. +You can use different tasks to generate output in [HTML](dokka-html.md), +[Javadoc](dokka-javadoc.md) or both [HTML and Javadoc](dokka-gradle.md#configure-documentation-output-format). -* `dokkaHtml` for single-project builds -* `dokkaHtmlMultiModule` for multi-project builds +**Set output directory** -By default, the output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`. +By default, the output directory is set to `/build/dokka/html` for both multi-project and single-project builds, +but you can [configure it](dokka-gradle.md#general-configuration). To learn more about using Dokka with Gradle, see [Gradle](dokka-gradle.md). 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-introduction.md b/docs/topics/dokka-introduction.md index 77110164ec..c0506765d5 100644 --- a/docs/topics/dokka-introduction.md +++ b/docs/topics/dokka-introduction.md @@ -6,8 +6,9 @@ Just like Kotlin itself, Dokka supports mixed-language projects. It understands [KDoc comments](https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax) and Java's [Javadoc comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html). -Dokka can generate documentation in multiple formats, including its own modern [HTML format](dokka-html.md), -multiple flavors of [Markdown](dokka-markdown.md), and Java's [Javadoc HTML](dokka-javadoc.md). +Dokka can generate documentation in multiple formats, including its own modern [HTML format](dokka-html.md), Java's [Javadoc HTML](dokka-javadoc.md), and +[GFM](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-gfm/README.md) and +[Jekyll](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-jekyll/README.md) flavors of Markdown. Here are some libraries that use Dokka for their API reference documentation: diff --git a/docs/topics/dokka-migration.md b/docs/topics/dokka-migration.md index dd0f145cf0..1111a080bd 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. @@ -39,12 +38,12 @@ Ensure that your project meets the minimum version requirements: > {style="note"} -Update the Dokka version to 2.0.0 in the `plugins {}` block of your project’s `build.gradle.kts` file: +Update the Dokka version to %dokkaVersion% in the `plugins {}` block of your project’s `build.gradle.kts` file: ```kotlin plugins { kotlin("jvm") version "2.1.10" - id("org.jetbrains.dokka") version "2.0.0" + id("org.jetbrains.dokka") version "%dokkaVersion%" } ``` @@ -133,7 +132,7 @@ Configuration in DGP v2: 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 // build.gradle.kts @@ -161,7 +160,7 @@ dokka { ``` - + ```kotlin // CustomPlugin.kt @@ -267,7 +266,7 @@ Configuration in DGP v2: 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 // build.gradle.kts @@ -284,7 +283,7 @@ dokka { ``` - + ```kotlin // CustomPlugin.kt @@ -442,7 +441,7 @@ Configuration in DGP v2: 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 // build.gradle.kts @@ -456,7 +455,7 @@ dokka { ``` - + ```kotlin // CustomPlugin.kt @@ -526,15 +525,15 @@ For an example of the DGP v2 configuration, see the DGP v2 allows you to extend its functionality by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/ae3840edb4e4afd7b3e3768a5fddfe8ec0e08f31/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts). Custom plugins enable additional processing or modifications to the documentation generation process. -### Share Dokka configuration across modules +### Share Dokka configuration across subprojects -DPG v2 moves away from using `subprojects {}` or `allprojects {}` to share configuration across modules. In future Gradle versions, +DPG v2 moves away from using `subprojects {}` or `allprojects {}` to share configuration across subprojects. In future Gradle versions, using these approaches will [lead to errors](https://docs.gradle.org/current/userguide/isolated_projects.html). Follow the steps below to properly share Dokka configuration in multi-module projects [with existing convention plugins](#multi-module-projects-with-convention-plugins) or [without convention plugins](#multi-module-projects-without-convention-plugins). -After sharing the Dokka configuration, you can aggregate the documentation from multiple modules into a single output. For more information, see +After sharing the Dokka configuration, you can aggregate the documentation from multiple subprojects into a single output. For more information, see [Update documentation aggregation in multi-module projects](#update-documentation-aggregation-in-multi-module-projects). > For a multi-module project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example). @@ -543,12 +542,12 @@ After sharing the Dokka configuration, you can aggregate the documentation from #### Multi-module projects without convention plugins -If your project doesn't use convention plugins, you can still share Dokka configurations by directly configuring each module. -This involves manually setting up the shared configuration in each module's `build.gradle.kts` file. While this approach is less centralized, +If your project doesn't use convention plugins, you can still share Dokka configurations by directly configuring each subproject. +This involves manually setting up the shared configuration in each subproject's `build.gradle.kts` file. While this approach is less centralized, it avoids the need for additional setups like convention plugins. Otherwise, if your project uses convention plugins, you can also share the Dokka configuration in multi-module projects -by creating a convention plugin in the `buildSrc` directory, and then applying the plugin to your modules (subprojects). +by creating a convention plugin in the `buildSrc` directory, and then applying the plugin to your subprojects. ##### Set up the buildSrc directory @@ -576,7 +575,7 @@ by creating a convention plugin in the `buildSrc` directory, and then applying t } dependencies { - implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0") + implementation("org.jetbrains.dokka:dokka-gradle-plugin:%dokkaVersion%") } ``` @@ -600,9 +599,9 @@ After setting up the `buildSrc` directory: You need to add the shared Dokka [configuration](#adjust-configuration-options) common to all subprojects within the `dokka {}` block. Also, you don't need to specify a Dokka version. The version is already set in the `buildSrc/build.gradle.kts` file. -##### Apply the convention plugin to your modules +##### Apply the convention plugin to your subprojects -Apply the Dokka convention plugin across your modules (subprojects) by adding it to each subproject's `build.gradle.kts` file: +Apply the Dokka convention plugin across your subprojects by adding it to each subproject's `build.gradle.kts` file: ```kotlin plugins { @@ -615,13 +614,13 @@ plugins { If you already have convention plugins, create a dedicated Dokka convention plugin following [Gradle's documentation](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:convention_plugins). Then, follow the steps to [set up the Dokka convention plugin](#set-up-the-dokka-convention-plugin) and -[apply it across your modules](#apply-the-convention-plugin-to-your-modules). +[apply it across your subprojects](#apply-the-convention-plugin-to-your-subprojects). ### Update documentation aggregation in multi-module projects -Dokka can aggregate the documentation from multiple modules (subprojects) into a single output or publication. +Dokka can aggregate the documentation from multiple subprojects into a single output or publication. -As [explained](#apply-the-convention-plugin-to-your-modules), apply the Dokka plugin to all documentable subprojects before aggregating the documentation. +As [explained](#apply-the-convention-plugin-to-your-subprojects), apply the Dokka plugin to all documentable subprojects before aggregating the documentation. Aggregation in DGP v2 uses the `dependencies {}` block instead of tasks and can be added in any `build.gradle.kts` file. @@ -647,7 +646,7 @@ dependencies { ### Change directory of aggregated documentation -When DGP aggregates modules, each subproject has its own subdirectory within the aggregated documentation. +When DGP aggregates subprojects, each subproject has its own subdirectory within the aggregated documentation. In DGP v2, the aggregation mechanism has been updated to better align with Gradle conventions. DGP v2 now preserves the full subproject directory to prevent conflicts when aggregating @@ -677,7 +676,7 @@ may become outdated, potentially causing `404` errors. #### Revert to the DGP v1 directory behavior -If your project depends on the directory structure used in DGP v1, you can revert this behavior by manually specifying the module directory. +If your project depends on the directory structure used in DGP v1, you can revert this behavior by manually specifying the subproject directory. Add the following configuration to the `build.gradle.kts` file of each subproject: ```kotlin @@ -688,7 +687,7 @@ plugins { } dokka { - // Overrides the module directory to match the V1 structure + // Overrides the subproject directory to match the V1 structure modulePath.set("maths") } ``` @@ -724,7 +723,7 @@ to generate output in HTML, Javadoc or both HTML and Javadoc. For more informati > 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"} +{style="warning"} The default output format for DGP v2 is HTML. However, you can choose to generate the API documentation in HTML, Javadoc, or both formats at the same time: @@ -734,10 +733,10 @@ or both formats at the same time: ```kotlin plugins { // Generates HTML documentation - id("org.jetbrains.dokka") version "2.0.0" + id("org.jetbrains.dokka") version "%dokkaVersion%" // Generates Javadoc documentation - id("org.jetbrains.dokka-javadoc") version "2.0.0" + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" // Keeping both plugin IDs generates both formats } @@ -758,6 +757,9 @@ Here is a list of the plugin `id` and Gradle task that correspond to each format > {style="tip"} +If you're using IntelliJ IDEA, you may see the `dokkaGenerateHtml` Gradle task. +This task is simply an alias of `dokkaGeneratePublicationHtml`. Both tasks perform exactly the same operation. + ### Address deprecations and removals * **Output format support:** DGP v2 only supports HTML and Javadoc output. Experimental formats like Markdown and Jekyll are no longer supported. @@ -786,75 +788,8 @@ 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). * [Get started with Dokka](dokka-get-started.md). -* [Learn more about Dokka plugins](dokka-plugins.md). +* [Learn more about Dokka plugins](dokka-plugins.md). \ No newline at end of file diff --git a/docs/topics/dokka-module-and-package-docs.md b/docs/topics/dokka-module-and-package-docs.md index d6c7af0baa..5eedc19bee 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) -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 @@ -54,22 +54,22 @@ To pass these files to Dokka, you need to use the relevant **includes** option f -Use the [includes](dokka-gradle.md#includes) option in [Source set configuration](dokka-gradle.md#source-set-configuration). +Use the `includes` option in [General configuration](dokka-gradle.md#general-configuration). -Use the [includes](dokka-maven.md#includes) option in [General configuration](dokka-maven.md#general-configuration). +Use the `includes` option in [General configuration](dokka-maven.md#general-configuration). -If you are using command line configuration, use the [includes](dokka-cli.md#includes-cli) option in +If you are using command line configuration, use the `includes` option in [Source set options](dokka-cli.md#source-set-options). -If you are using JSON configuration, use the [includes](dokka-cli.md#includes-json) option in +If you are using JSON configuration, use the `includes` option in [General configuration](dokka-cli.md#general-configuration). diff --git a/docs/topics/dokka-plugins.md b/docs/topics/dokka-plugins.md index 8fe048d7c5..c17b7f9b26 100644 --- a/docs/topics/dokka-plugins.md +++ b/docs/topics/dokka-plugins.md @@ -1,5 +1,10 @@ [//]: # (title: Dokka plugins) +> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. +> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md). +> +{style="note"} + Dokka was built from the ground up to be easily extensible and highly customizable, which allows the community to implement plugins for missing or very specific features that are not provided out of the box. @@ -13,11 +18,11 @@ If you want to learn how to create Dokka plugins, see ## Apply Dokka plugins -Dokka plugins are published as separate artifacts, so to apply a Dokka plugin you only need to add it as a dependency. -From there, the plugin extends Dokka by itself - no further action is needed. +Dokka plugins are published as separate artifacts, so to apply a Dokka plugin, you only need to add it as a dependency. +From there, the plugin extends Dokka by itself—no further action is needed. > Plugins that use the same extension points or work in a similar way can interfere with each other. -> This may lead to visual bugs, general undefined behaviour or even failed builds. However, it should not lead to +> This may lead to visual bugs, general undefined behavior or even failed builds. However, it should not lead to > concurrency issues since Dokka does not expose any mutable data structures or objects. > > If you notice problems like this, it's a good idea to check which plugins are applied and what they do. @@ -30,57 +35,39 @@ to your project: -> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, several configuration options, Gradle tasks, and steps to generate your documentation have been updated, including: -> -> * [Configure Dokka plugins](dokka-migration.md#configure-dokka-plugins) -> * [Work with multi-module projects](dokka-migration.md#share-dokka-configuration-across-modules) -> -> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). -> -> {style="note"} - -The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply plugins universally or -for a specific output format only. +The way to apply Dokka plugins is: ```kotlin -dependencies { - // Is applied universally - dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%") - - // Is applied for the single-module dokkaHtml task only - dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} - // Is applied for HTML format in multi-project builds - dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%") +dependencies { + dokkaPlugin("org.jetbrains.dokka:mathjax-plugin") } ``` -> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within -> subprojects as well as in their parent project. +> * Built-in plugins (like HTML and Javadoc) are always applied automatically. You only configure them and do not need dependencies for them. > +> * When documenting multi-module projects (multi-project builds), you need to [share Dokka configuration and plugins across subprojects](dokka-gradle.md#multi-project-configuration). +> {style="note"} -The Gradle plugin for Dokka creates convenient dependency configurations that allow you to apply Dokka plugins universally or -for a specific output format only. - ```groovy -dependencies { - // Is applied universally - dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:%dokkaVersion%' - - // Is applied for the single-module dokkaHtml task only - dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%' +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} - // Is applied for HTML format in multi-project builds - dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:%dokkaVersion%' +dependencies { + dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin' } ``` -> When documenting [multi-project](dokka-gradle.md#multi-project-builds) builds, you need to apply Dokka plugins within -> subprojects as well as in their parent project. +> When documenting [multi-project](dokka-gradle.md#multi-project-configuration) builds, +> you need to [share Dokka configuration across subprojects](dokka-gradle.md#multi-project-configuration). > {style="note"} @@ -139,76 +126,45 @@ If you are using [JSON configuration](dokka-cli.md#run-with-json-configuration), Dokka plugins can also have configuration options of their own. To see which options are available, consult the documentation of the plugins you are using. -Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](dokka-html.md) -documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets -(`customStyleSheets` option), and by modifying the footer message (`footerMessage` option): +Let's have a look at how you can configure the built-in HTML plugin by adding a custom image to the assets +(`customAssets` option), +custom style sheets (`customStyleSheets` option), and a modified footer message (`footerMessage` option): -Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to -the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes: +To configure Dokka plugins in a type-safe way, use the `dokka.pluginsConfiguration {}` block: ```kotlin -import org.jetbrains.dokka.base.DokkaBase -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.base.DokkaBaseConfiguration - -buildscript { - dependencies { - classpath("org.jetbrains.dokka:dokka-base:%dokkaVersion%") - } -} - -tasks.withType().configureEach { - pluginConfiguration { - customAssets = listOf(file("my-image.png")) - customStyleSheets = listOf(file("my-styles.css")) - footerMessage = "(c) 2022 MyOrg" +dokka { + pluginsConfiguration.html { + customAssets.from("logo.png") + customStyleSheets.from("styles.css") + footerMessage.set("(c) Your Company") } } ``` -Alternatively, plugins can be configured via JSON. With this method, no additional dependencies are needed. - -```kotlin -import org.jetbrains.dokka.gradle.DokkaTask +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). -tasks.withType().configureEach { - val dokkaBaseConfiguration = """ - { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" - } - """ - pluginsMapConfiguration.set( - mapOf( - // fully qualified plugin name to json configuration - "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration - ) - ) -} -``` +Dokka allows you +to extend its functionality +by [configuring custom plugins](https://github.com/Kotlin/dokka/blob/v2.1.0/examples/gradle-v2/custom-dokka-plugin-example/demo-library/build.gradle.kts). +Custom plugins enable additional processing or modifications to the documentation generation process. ```groovy -import org.jetbrains.dokka.gradle.DokkaTask - -tasks.withType(DokkaTask.class) { - String dokkaBaseConfiguration = """ - { - "customAssets": ["${file("assets/my-image.png")}"], - "customStyleSheets": ["${file("assets/my-styles.css")}"], - "footerMessage": "(c) 2022 MyOrg" +dokka { + pluginsConfiguration { + html { + customAssets.from("logo.png") + customStyleSheets.from("styles.css") + footerMessage.set("(c) Your Company") + } } - """ - pluginsMapConfiguration.set( - // fully qualified plugin name to json configuration - ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] - ) } ``` @@ -281,7 +237,9 @@ 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 | +| [GFM plugin](https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-gfm) | Adds the ability to generate documentation in GitHub Flavoured Markdown format | +| [Jekyll plugin](https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-jekyll) | Adds the ability to generate documentation in Jekyll Flavoured Markdown format | 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..6cc2f937a4 100644 --- a/docs/topics/formats/dokka-html.md +++ b/docs/topics/formats/dokka-html.md @@ -1,22 +1,39 @@ [//]: # (title: HTML) -HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release. +> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. +> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md). +> +{style="note"} + +HTML is Dokka's default and recommended output format. +It provides support for Kotlin Multiplatform, Android, and Java projects. +Additionally, you can use the HTML format to document both single and multi-project builds. -You can see an example of the output by browsing documentation -for [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/). +For examples of the HTML output format, check the following docs: +* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/) +* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html) +* [Hexagon](https://hexagontk.com/stable/api/) +* [Ktor](https://api.ktor.io/) +* [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/) +* [Gradle](https://docs.gradle.org/current/kotlin-dsl/index.html) ## Generate HTML documentation HTML as an output format is supported by all runners. To generate HTML documentation, follow these steps depending on your build tool or runner: -* For [Gradle](dokka-gradle.md#generate-documentation), run `dokkaHtml` or `dokkaHtmlMultiModule` tasks. +* For [Gradle](dokka-gradle.md#generate-documentation), run the following tasks: + * `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). + This is the recommended task for most users. When using this task in IntelliJ IDEA, it logs a clickable link to the output. + * `dokkaGeneratePublicationHtml` to generate documentation only in HTML format. This task exposes the output directory + as an `@OutputDirectory`. Use this task when you need to consume the generated files in other Gradle tasks, such + as uploading them to a server, moving them into a GitHub Pages directory, or packaging them into a `javadoc.jar`. + This task is intentionally not shown in Gradle task groups because it is not meant for everyday use. - > 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"} + > If you're using IntelliJ IDEA, you may see the `dokkaGenerateHtml` Gradle task. + > This task is simply an alias of `dokkaGeneratePublicationHtml`. Both tasks perform exactly the same operation. + > + {style="tip"} * 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,59 +49,23 @@ 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 - } -} -``` - -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 +// 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) } - """ - pluginsMapConfiguration.set( - mapOf( - // fully qualified plugin name to json configuration - "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration - ) - ) } ``` @@ -92,23 +73,19 @@ tasks.withType().configureEach { ```groovy -import org.jetbrains.dokka.gradle.DokkaTask - -tasks.withType(DokkaTask.class) { - String 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 +// build.gradle + +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) + } } - """ - pluginsMapConfiguration.set( - // fully qualified plugin name to json configuration - ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] - ) } ``` @@ -173,7 +150,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 +190,16 @@ You can provide your own images to be bundled with documentation by using the `c These files are copied to the `/images` directory. +You can use the `customAssets` property with collections of +files +[(`FileCollection`)](https://docs.gradle.org/8.10/userguide/lazy_configuration.html#working_with_files_in_lazy_properties): + +```kotlin +customAssets.from("example.png", "example2.png") +``` + It's possible to override Dokka's images and icons by providing files with the same name. The most -useful and relevant one being `logo-icon.svg`, which is the image that's used in the header. The rest is mostly icons. +useful and relevant one is `logo-icon.svg`, which is the image used in the header. The rest is mostly icons. You can find all images used by Dokka on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-base/src/main/resources/dokka/images). @@ -240,7 +225,7 @@ You can modify text in the footer by using the `footerMessage` [configuration op Dokka provides the ability to modify [FreeMarker](https://freemarker.apache.org/) templates used for generating documentation pages. -You can change the header completely, add your own banners/menus/search, load analytics, change body styling and so on. +You can change the header completely, add your own banners/menus/search, load analytics, change body styling, and so on. Dokka uses the following templates: @@ -252,7 +237,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 +258,11 @@ The following variables are available inside all templates: | `${pathToRoot}` | The path to root from the current page. It's useful for locating assets and is available only within the `template_cmd` directive. | Variables `projectName` and `pathToRoot` are available only within the `template_cmd` directive as they require more -context and thus they need to be resolved at later stages by the [MultiModule](dokka-gradle.md#multi-project-builds) task: +context, and thus they need to be resolved at later stages: ```html <@template_cmd name="projectName"> - ${projectName} + ${projectName} ``` @@ -288,4 +274,4 @@ You can also use the following Dokka-defined [directives](https://freemarker.apa |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `<@content/>` | The main page content. | | `<@resources/>` | Resources such as scripts and stylesheets. | -| `<@version/>` | The module version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) is applied, it is replaced with a version navigator. | +| `<@version/>` | The subproject version taken from configuration. If the [versioning plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-versioning) is applied, it is replaced with a version navigator. | diff --git a/docs/topics/formats/dokka-javadoc.md b/docs/topics/formats/dokka-javadoc.md index a7f42c463e..fc688f9eb9 100644 --- a/docs/topics/formats/dokka-javadoc.md +++ b/docs/topics/formats/dokka-javadoc.md @@ -1,10 +1,10 @@ [//]: # (title: Javadoc) + -> The Javadoc output format is still in Alpha, so you may find bugs and experience migration issues when using it. -> Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed. -> **You use it at your own risk.** +> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. +> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md). > -{style="warning"} +{style="note"} Dokka's Javadoc output format is a lookalike of Java's [Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html). @@ -12,34 +12,39 @@ Dokka's Javadoc output format is a lookalike of Java's It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation or an exact copy. -![Screenshot of javadoc output format](javadoc-format-example.png){width=706} +![Screenshot of Javadoc output format](javadoc-format-example.png){width=706} All Kotlin code and signatures are rendered as seen from Java's perspective. This is achieved with our [Kotlin as Java Dokka plugin](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-kotlin-as-java), which comes bundled and applied by default for this format. The Javadoc output format is implemented as a [Dokka plugin](dokka-plugins.md), and it is maintained by the Dokka team. -It is open source and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-javadoc). +It is open source, +and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-javadoc). ## Generate Javadoc documentation -> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, [the Gradle tasks to generate documentation changed](dokka-migration.md#select-documentation-output-format). -> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). +> The Javadoc format does not support multi-project builds or Kotlin Multiplatform projects. > -> The Javadoc format does not support multiplatform projects. -> -{style="warning"} +{style="tip"} -The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Javadoc output format included. You can use the following tasks: +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Javadoc output format included. +You need to apply the corresponding plugin id in the `plugins {}` block of your project's `build.gradle.kts` file: + +```kotlin +plugins { + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" +} +``` + +Once you applied the plugin, you can run the following tasks: -| **Task** | **Description** | -|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `dokkaJavadoc` | Generates Javadoc documentation for a single project. | -| `dokkaJavadocCollector` | A [`Collector`](dokka-gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJavadoc` for every subproject and merges all outputs into a single virtual project. | +* `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). +* `dokkaGeneratePublicationJavadoc` to generate documentation only in Javadoc format. The `javadoc.jar` file can be generated separately. For more information, see [Building `javadoc.jar`](dokka-gradle.md#build-javadoc-jar). diff --git a/docs/topics/formats/dokka-markdown.md b/docs/topics/formats/dokka-markdown.md deleted file mode 100644 index a78f42ac17..0000000000 --- a/docs/topics/formats/dokka-markdown.md +++ /dev/null @@ -1,175 +0,0 @@ -[//]: # (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. - -These formats give you more freedom in terms of hosting documentation as the output can be embedded right into your -documentation website. For example, see [OkHttp's API reference](https://square.github.io/okhttp/5.x/okhttp/okhttp3/) -pages. - -Markdown output formats are implemented as [Dokka plugins](dokka-plugins.md), maintained by the Dokka team, and -they are open source. - -## GFM - -The GFM output format generates documentation in [GitHub Flavored Markdown](https://github.github.com/gfm/). - - - - -The [Gradle plugin for Dokka](dokka-gradle.md) comes with the GFM output format included. You can use the following tasks with it: - -| **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. | - - - - -Since GFM format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to apply it as a plugin -dependency: - -```xml - - org.jetbrains.dokka - dokka-maven-plugin - ... - - - - org.jetbrains.dokka - gfm-plugin - %dokkaVersion% - - - - -``` - -After configuring this, running the `dokka:dokka` goal produces documentation in GFM format. - -For more information, see the Maven plugin documentation for [Other output formats](dokka-maven.md#other-output-formats). - - - - -Since 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`. - -Via [command line options](dokka-cli.md#run-with-command-line-options): - -```Bash -java -jar dokka-cli-%dokkaVersion%.jar \ - -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar" \ - ... -``` - -Via [JSON configuration](dokka-cli.md#run-with-json-configuration): - -```json -{ - ... - "pluginsClasspath": [ - "./dokka-base-%dokkaVersion%.jar", - "...", - "./gfm-plugin-%dokkaVersion%.jar" - ], - ... -} -``` - -For more information, see the CLI runner's documentation for [Other output formats](dokka-cli.md#other-output-formats). - - - - -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. - - - - -The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Jekyll output format included. You can use the following tasks with it: - -| **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. | - - - - -Since Jekyll format is implemented as a [Dokka plugin](dokka-plugins.md#apply-dokka-plugins), you need to apply it as a plugin -dependency: - -```xml - - org.jetbrains.dokka - dokka-maven-plugin - ... - - - - org.jetbrains.dokka - jekyll-plugin - %dokkaVersion% - - - - -``` - -After configuring this, running the `dokka:dokka` goal produces documentation in GFM format. - -For more information, see the Maven plugin's documentation for [Other output formats](dokka-maven.md#other-output-formats). - - - - -Since 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`: - -Via [command line options](dokka-cli.md#run-with-command-line-options): - -```Bash -java -jar dokka-cli-%dokkaVersion%.jar \ - -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar;./jekyll-plugin-%dokkaVersion%.jar" \ - ... -``` - -Via [JSON configuration](dokka-cli.md#run-with-json-configuration): - -```json -{ - ... - "pluginsClasspath": [ - "./dokka-base-%dokkaVersion%.jar", - "...", - "./gfm-plugin-%dokkaVersion%.jar", - "./jekyll-plugin-%dokkaVersion%.jar" - ], - ... -} -``` - -For more information, see the CLI runner's documentation for [Other output formats](dokka-cli.md#other-output-formats). - - - - -You can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-jekyll). diff --git a/docs/topics/runners/dokka-cli.md b/docs/topics/runners/dokka-cli.md index b1cc978838..2efed3fed8 100644 --- a/docs/topics/runners/dokka-cli.md +++ b/docs/topics/runners/dokka-cli.md @@ -112,7 +112,7 @@ By default, the `dokka-base` artifact contains the [HTML](dokka-html.md) output All other output formats are implemented as [Dokka plugins](dokka-plugins.md). In order to use them, you have to put them on the plugins classpath. -For example, if you want to generate documentation in the experimental [GFM](dokka-markdown.md#gfm) output format, you need to download and +For example, if you want to generate documentation in the experimental [GFM](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-gfm/README.md) output format, you need to download and pass gfm-plugin's JAR ([download](https://repo1.maven.org/maven2/org/jetbrains/dokka/gfm-plugin/%dokkaVersion%/gfm-plugin-%dokkaVersion%.jar)) into the `pluginsClasspath` configuration option. @@ -140,7 +140,7 @@ Via JSON configuration: With the GFM plugin passed to `pluginsClasspath`, the CLI runner generates documentation in the GFM output format. -For more information, see [Markdown](dokka-markdown.md) and [Javadoc](dokka-javadoc.md#generate-javadoc-documentation) pages. +For more information, see [GFM](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-gfm/README.md) and [Javadoc](dokka-javadoc.md#generate-javadoc-documentation) pages. ## Command line options diff --git a/docs/topics/runners/dokka-gradle.md b/docs/topics/runners/dokka-gradle.md index 3a7b575015..2e74da8ed3 100644 --- a/docs/topics/runners/dokka-gradle.md +++ b/docs/topics/runners/dokka-gradle.md @@ -1,31 +1,26 @@ [//]: # (title: Gradle) -> These instructions reflect Dokka Gradle plugin v1 configuration and tasks. Starting from Dokka 2.0.0, several configuration options, Gradle tasks, and steps to generate your documentation have been updated, including: -> -> * [Adjust configuration options](dokka-migration.md#adjust-configuration-options) -> * [Work with multi-module projects](dokka-migration.md#share-dokka-configuration-across-modules) -> * [Generate documentation with the updated tasks](dokka-migration.md#generate-documentation-with-the-updated-task) -> * [Specify an output directory](dokka-migration.md#output-directory) -> -> For more details and the full list of changes in Dokka Gradle Plugin v2, see the [Migration guide](dokka-migration.md). +> This guide applies to Dokka Gradle plugin (DGP) v2 mode. The previous DGP v1 mode is no longer supported. +> If you're upgrading from v1 to v2 mode, see the [Migration guide](dokka-migration.md). > {style="note"} - To generate documentation for a Gradle-based project, you can use the [Gradle plugin for Dokka](https://plugins.gradle.org/plugin/org.jetbrains.dokka). -It comes with basic autoconfiguration for your project, has convenient [Gradle tasks](#generate-documentation) for -generating documentation, and provides a great deal of [configuration options](#configuration-options) to +The Dokka Gradle plugin (DGP) comes with basic autoconfiguration for your project, +includes [Gradle tasks](#generate-documentation) for +generating documentation, and provides [configuration options](#configuration-options) to customize the output. -You can play around with Dokka and see how it can be configured for various projects by visiting our -[Gradle example projects](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle). +You can play around with Dokka and explore how to configure it for various projects in our +[Gradle example projects](https://github.com/Kotlin/dokka/tree/2.0.0/examples/gradle-v2). ## Apply Dokka The recommended way of applying the Gradle plugin for Dokka is with the -[plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block): +[plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block). +Add it in the `plugins {}` block of your project’s `build.gradle.kts` file: @@ -48,110 +43,119 @@ plugins { -When documenting [multi-project](#multi-project-builds) builds, you need to apply the Gradle plugin for Dokka -within subprojects as well. You can use `allprojects {}` or `subprojects {}` Gradle configurations to achieve that: +When documenting multi-project builds, you need to apply the plugin explicitly to every subproject you want to document. +You can configure Dokka directly in each subproject or share Dokka configuration across subprojects using a convention plugin. +For more information, see +how to configure [single-project](#single-project-configuration) and [multi-project](#multi-project-configuration) builds. - - +> * Under the hood, +> Dokka uses the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) +> to automatically configure [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) +> for which documentation is generated. Make sure to apply the Kotlin Gradle Plugin or +> [configure source sets](#source-set-configuration) manually. +> +> * If you are using Dokka in a +> [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins), +> add the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) +> as a dependency to ensure it works properly. +> +{style="tip"} -```kotlin -subprojects { - apply(plugin = "org.jetbrains.dokka") -} -``` +If you are not able to use the plugins DSL, you can apply the plugin using +[the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application). - - +## Enable build cache and configuration cache -```groovy -subprojects { - apply plugin: 'org.jetbrains.dokka' -} -``` +DGP supports Gradle build cache and configuration cache, improving build performance. - - +* To enable build cache, follow instructions in the [Gradle build cache documentation](https://docs.gradle.org/current/userguide/build_cache.html#sec:build_cache_enable). +* To enable configuration cache, follow instructions in the [Gradle configuration cache documentation](https://docs.gradle.org/current/userguide/configuration_cache.html#config_cache:usage:enable ). -See [Configuration examples](#configuration-examples) if you are not sure where to apply Dokka. +## Generate documentation -> Under the hood, Dokka uses the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) -> to perform autoconfiguration of [source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) -> for which documentation is to be generated. Make sure to apply the Kotlin Gradle Plugin or -> [configure source sets](#source-set-configuration) manually. -> -{style="note"} +The Dokka Gradle plugin comes with [HTML](dokka-html.md) and [Javadoc](dokka-javadoc.md) output formats +built in. -> If you are using Dokka in a -> [precompiled script plugin](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompiled_plugins), -> you need to add the [Kotlin Gradle plugin](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin) -> as a dependency for it to work properly. -> -{style="note"} +Use the following Gradle task to generate documentation: -If you cannot use the plugins DSL for some reason, you can use -[the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application) of applying -plugins. +```shell +./gradlew :dokkaGenerate +``` -## Generate documentation +The key behavior of the `dokkaGenerate` Gradle task is: -The Gradle plugin for Dokka comes with [HTML](dokka-html.md), [Markdown](dokka-markdown.md) and [Javadoc](dokka-javadoc.md) output formats -built in. It adds a number of tasks for generating documentation, both for [single](#single-project-builds) -and [multi-project](#multi-project-builds) builds. +* This task generates documentation for both [single](#single-project-configuration) + and [multi-project](#multi-project-configuration) builds. +* By default, the documentation output format is HTML. + You can also generate Javadoc or both HTML and Javadoc formats + by [adding the appropriate plugins](#configure-documentation-output-format). +* The generated documentation is automatically placed in the `build/dokka/html` + directory for both single and multi-project builds. + You can [change the location (`outputDirectory`)](#general-configuration). -### Single-project builds +### Configure documentation output format -Use the following tasks to build documentation for simple, single-project applications and libraries: +> The Javadoc output format is in [Alpha](https://kotlinlang.org/docs/components-stability.html#stability-levels-explained). +> You may find bugs and experience migration issues when using it. +> Successful integration with tools that accept Javadoc as input is not guaranteed. +> Use it at your own risk. +> +{style="warning"} -| **Task** | **Description** | -|-------------|----------------------------------------------------------| -| `dokkaHtml` | Generates documentation in [HTML](dokka-html.md) format. | +You can choose to generate the API documentation in HTML, Javadoc, +or both formats at the same time: -#### Experimental formats +1. Place the corresponding plugin `id` in the `plugins {}` block of your project's `build.gradle.kts` file: -| **Task** | **Description** | -|----------------|-------------------------------------------------------------------------------------------| -| `dokkaGfm` | Generates documentation in [GitHub Flavored Markdown](dokka-markdown.md#gfm) format. | -| `dokkaJavadoc` | Generates documentation in [Javadoc](dokka-javadoc.md) format. | -| `dokkaJekyll` | Generates documentation in [Jekyll compatible Markdown](dokka-markdown.md#jekyll) format. | + ```kotlin + plugins { + // Generates HTML documentation + id("org.jetbrains.dokka") version "%dokkaVersion%" -By default, generated documentation is located in the `build/dokka/{format}` directory of your project. -The output location, among other things, can be [configured](#configuration-examples). + // Generates Javadoc documentation + id("org.jetbrains.dokka-javadoc") version "%dokkaVersion%" -### Multi-project builds + // Keeping both plugin IDs generates both formats + } + ``` -For documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), make sure -that you [apply the Gradle plugin for Dokka](#apply-dokka) within subprojects that you want to generate documentation -for, as well as in their parent project. +2. Run the corresponding Gradle task. -#### MultiModule tasks + Here is a list of the plugin `id` and Gradle task that correspond to each format: -`MultiModule` tasks generate documentation for each subproject individually via [`Partial`](#partial-tasks) tasks, -collect and process all outputs, and produce complete documentation with a common table of contents and resolved -cross-project references. + | | **HTML** | **Javadoc** | **Both** | + |-------------|-------------------------------------------|----------------------------------------------|-----------------------------------| + | Plugin `id` | `id("org.jetbrains.dokka")` | `id("org.jetbrains.dokka-javadoc")` | Use both HTML and Javadoc plugins | + | Gradle task | `./gradlew :dokkaGeneratePublicationHtml` | `./gradlew :dokkaGeneratePublicationJavadoc` | `./gradlew :dokkaGenerate` | -Dokka creates the following tasks for **parent** projects automatically: + > * The `dokkaGenerate` task generates documentation in all available formats based on the applied plugins. + > If both the HTML and Javadoc plugins are applied, + > you can choose to generate only HTML by running the `dokkaGeneratePublicationHtml` task, + > or only Javadoc by running the `dokkaGeneratePublicationJavadoc` task. + > + {style="tip"} -| **Task** | **Description** | -|------------------------|------------------------------------------------------------------------------| -| `dokkaHtmlMultiModule` | Generates multi-module documentation in [HTML](dokka-html.md) output format. | +If you're using IntelliJ IDEA, you may see the `dokkaGenerateHtml` Gradle task. +This task is simply an alias of `dokkaGeneratePublicationHtml`. Both tasks perform exactly the same operation. -#### Experimental formats (multi-module) +### Aggregate documentation output in multi-project builds -| **Task** | **Description** | -|--------------------------|---------------------------------------------------------------------------------------------------------------| -| `dokkaGfmMultiModule` | Generates multi-module documentation in [GitHub Flavored Markdown](dokka-markdown.md#gfm) output format. | -| `dokkaJekyllMultiModule` | Generates multi-module documentation in [Jekyll compatible Markdown](dokka-markdown.md#jekyll) output format. | +Dokka can aggregate documentation from multiple subprojects into a single output or publication. -> The [Javadoc](dokka-javadoc.md) output format does not have a `MultiModule` task, but a [`Collector`](#collector-tasks) task can -> be used instead. -> -{style="note"} +You have to [apply the Dokka plugin](#apply-the-convention-plugin-to-your-subprojects) to +all documentable subprojects before aggregating the documentation. -By default, you can find ready-to-use documentation under `{parentProject}/build/dokka/{format}MultiModule` directory. +To aggregate documentation from multiple subprojects, add the `dependencies {}` +block in the `build.gradle.kts` file of the root project: -#### MultiModule results +```kotlin +dependencies { + dokka(project(":childProjectA:")) + dokka(project(":childProjectB:")) +} +``` -Given a project with the following structure: +Given a project with the following structure: ```text . @@ -164,70 +168,40 @@ Given a project with the following structure: └── ChildProjectBClass ``` -These pages are generated after running `dokkaHtmlMultiModule`: +The generated documentation is aggregated as follows: ![Screenshot for output of dokkaHtmlMultiModule task](dokkaHtmlMultiModule-example.png){width=600} -See our [multi-module project example](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/examples/gradle/dokka-multimodule-example) +See our [multi-project example](https://github.com/Kotlin/dokka/tree/2.0.0/examples/gradle-v2/multimodule-example) for more details. -#### Collector tasks - -Similar to `MultiModule` tasks, `Collector` tasks are created for each parent project: `dokkaHtmlCollector`, -`dokkaGfmCollector`, `dokkaJavadocCollector` and `dokkaJekyllCollector`. - -A `Collector` task executes the corresponding [single-project task](#single-project-builds) for each subproject (for -example, -`dokkaHtml`), and merges all outputs into a single virtual project. +#### Directory of aggregated documentation -The resulting documentation looks as if you have a single-project -build that contains all declarations from the subprojects. +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. -> Use the `dokkaJavadocCollector` task if you need to create Javadoc documentation for your multi-project build. -> -{style="tip"} - -#### Collector results - -Given a project with the following structure: +For example, given a project with an aggregation in `:turbo-lib` and a nested subproject `:turbo-lib:maths`, +the generated documentation is placed under: ```text -. -└── parentProject/ - ├── childProjectA/ - │ └── demo/ - │ └── ChildProjectAClass - └── childProjectB/ - └── demo/ - └── ChildProjectBClass +turbo-lib/build/dokka/html/turbo-lib/maths/ ``` -These pages are generated after running `dokkaHtmlCollector`: +You can revert this behavior by manually specifying the subproject directory. +Add the following configuration to the `build.gradle.kts` file of each subproject: -![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 - -Each subproject has `Partial` tasks created for it: `dokkaHtmlPartial`,`dokkaGfmPartial`, -and `dokkaJekyllPartial`. - -These tasks are not intended to be run independently, they are called by the parent's -[MultiModule](#multimodule-tasks) task. - -However, you can [configure](#subproject-configuration) `Partial` tasks to customize Dokka for your subprojects. +```kotlin +// /turbo-lib/maths/build.gradle.kts -> Output generated by `Partial` tasks contains unresolved HTML templates and references, so it cannot be used -> on its own without post-processing done by the parent's [`MultiModule`](#multimodule-tasks) task. -> -{style="warning"} +plugins { + id("org.jetbrains.dokka") +} -> If you want to generate documentation for a single subproject only, use -> [single-project tasks](#single-project-builds). For example, `:subprojectName:dokkaHtml`. -> -{style="note"} +dokka { + // Overrides the subproject directory + modulePath.set("maths") +} +``` ## Build javadoc.jar @@ -245,15 +219,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") } ``` @@ -262,16 +238,18 @@ tasks.register("dokkaJavadocJar") { ```groovy -tasks.register('dokkaHtmlJar', Jar.class) { - dependsOn(dokkaHtml) - from(dokkaHtml) - archiveClassifier.set("html-docs") +// To generate documentation in HTML +tasks.register('dokkaHtmlJar', Jar) { + description = 'A HTML Documentation JAR containing Dokka HTML' + from(tasks.named('dokkaGeneratePublicationHtml').flatMap { it.outputDirectory }) + archiveClassifier.set('html-doc') } -tasks.register('dokkaJavadocJar', Jar.class) { - dependsOn(dokkaJavadoc) - from(dokkaJavadoc) - archiveClassifier.set("javadoc") +// To generate documentation in Javadoc +tasks.register('dokkaJavadocJar', Jar) { + description = 'A Javadoc JAR containing Dokka Javadoc' + from(tasks.named('dokkaGeneratePublicationJavadoc').flatMap { it.outputDirectory }) + archiveClassifier.set('javadoc') } ``` @@ -298,8 +276,9 @@ see [Multi-project configuration](#multi-project-configuration). ### Single-project configuration -Single-project builds usually have only one `build.gradle.kts` or `build.gradle` file in the root of the project, -and typically have the following structure: +Single-project builds usually have only one `build.gradle.kts` +or `build.gradle` file in the root of the project. +They can be either single-platform or multiplatform and typically have the following structure: @@ -366,26 +345,30 @@ Multiplatform: -In such projects, you need to apply Dokka and its configuration in the root `build.gradle.kts` or `build.gradle` file. - -You can configure tasks and output formats individually: +Apply the Dokka Gradle plugin in your root `build.gradle.kts` file and configure it using the top-level `dokka {}` DSL: -Inside `./build.gradle.kts`: - ```kotlin plugins { id("org.jetbrains.dokka") version "%dokkaVersion%" } -tasks.dokkaHtml { - outputDirectory.set(layout.buildDirectory.dir("documentation/html")) -} +dokka { + dokkaPublications.html { + moduleName.set("MyProject") + outputDirectory.set(layout.buildDirectory.dir("documentation/html")) + includes.from("README.md") + } -tasks.dokkaGfm { - outputDirectory.set(layout.buildDirectory.dir("documentation/markdown")) + dokkaSourceSets.main { + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl.set(URI("https://github.com/your-repo")) + remoteLineSuffix.set("#L") + } + } } ``` @@ -399,79 +382,22 @@ plugins { id 'org.jetbrains.dokka' version '%dokkaVersion%' } -dokkaHtml { - outputDirectory.set(file("build/documentation/html")) -} - -dokkaGfm { - outputDirectory.set(file("build/documentation/markdown")) -} -``` - - - - -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) +dokka { + dokkaPublications { + html { + moduleName.set("MyProject") + outputDirectory.set(layout.buildDirectory.dir("documentation/html")) + includes.from("README.md") } } -} -``` - - - - -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) + dokkaSourceSets { + named("main") { + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl.set(new URI("https://github.com/your-repo")) + remoteLineSuffix.set("#L") + } } } } @@ -480,11 +406,17 @@ tasks.withType(DokkaTask.class) { +This configuration applies Dokka to your project, +sets up the documentation output directory, and defines the main source set. +You can extend it further by adding custom assets, visibility filters, +or plugin configurations within the same `dokka {}` block. +For more information, see [Configuration options](#configuration-options). + ### Multi-project configuration -Gradle's [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html) are more complex -in structure and configuration. They usually have multiple nested `build.gradle.kts` or `build.gradle` files, and -typically have the following structure: +[Multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html) +usually contain several +nested `build.gradle.kts` files and have a structure similar to the following: @@ -531,188 +463,236 @@ typically have the following structure: -In this case, there are multiple ways of applying and configuring Dokka. +Single and multi-project documentation share the same +[configuration model using the top-level `dokka {}` DSL](#single-project-configuration). +In multi-project builds, +you configure Dokka in the root project and can optionally share settings across subprojects. -#### Subproject configuration +To share Dokka configuration across subprojects, you can use either: -To configure subprojects in a multi-project build, you need to configure [`Partial`](#partial-tasks) tasks. - -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: - - - +* [Direct configuration in multi-project builds requiring convention plugins](#direct-configuration-in-multi-project-builds-requiring-convention-plugins) +* [Convention plugins](#multi-project-builds-with-convention-plugins) -In the root `./build.gradle.kts`: +After sharing Dokka configuration, you can aggregate the documentation from multiple subprojects into a single output. +For more information, see +[Aggregate documentation output in multi-project-builds](#aggregate-documentation-output-in-multi-project-builds). -```kotlin -import org.jetbrains.dokka.gradle.DokkaTaskPartial +> For a multi-project example, see the [Dokka GitHub repository](https://github.com/Kotlin/dokka/tree/master/examples/gradle-v2/multimodule-example). +> +{style="tip"} -plugins { - id("org.jetbrains.dokka") version "%dokkaVersion%" -} +#### Direct configuration in multi-project builds requiring convention plugins -subprojects { - apply(plugin = "org.jetbrains.dokka") +If your project doesn't use convention plugins, you can share Dokka configurations by directly configuring each subproject. +This involves manually setting up the shared configuration in each subproject's `build.gradle.kts` file. +While this approach is less centralized, +it avoids the need for additional setups like convention plugins. - // configure only the HTML task - tasks.dokkaHtmlPartial { - outputDirectory.set(layout.buildDirectory.dir("docs/partial")) - } +Follow the next steps to configure your multi-project builds without convention plugins. - // configure all format tasks at once - tasks.withType().configureEach { - dokkaSourceSets.configureEach { - includes.from("README.md") - } - } -} -``` +##### Set up the buildSrc directory - - +1. In your project root, create a `buildSrc` directory containing two files: -In the root `./build.gradle`: + * `settings.gradle.kts` + * `build.gradle.kts` -```groovy -import org.jetbrains.dokka.gradle.DokkaTaskPartial +2. In the `buildSrc/settings.gradle.kts` file, add the following snippet: -plugins { - id 'org.jetbrains.dokka' version '%dokkaVersion%' -} + ```kotlin + rootProject.name = "buildSrc" + ``` -subprojects { - apply plugin: 'org.jetbrains.dokka' +3. In the `buildSrc/build.gradle.kts` file, add the following snippet: - // configure only the HTML task - dokkaHtmlPartial { - outputDirectory.set(file("build/docs/partial")) + ```kotlin + plugins { + `kotlin-dsl` } - - // configure all format tasks at once - tasks.withType(DokkaTaskPartial.class) { - dokkaSourceSets.configureEach { - includes.from("README.md") - } + + repositories { + mavenCentral() + gradlePluginPortal() } -} -``` - - - - -Alternatively, you can apply and configure Dokka within subprojects individually. + + dependencies { + implementation("org.jetbrains.dokka:dokka-gradle-plugin:%dokkaVersion%") + } + ``` -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`: +##### Set up the Dokka convention plugin - - +After setting up the `buildSrc` directory, set up the Dokka convention plugin: -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 -apply(plugin = "org.jetbrains.dokka") + ```kotlin + plugins { + id("org.jetbrains.dokka") + } -// configuration for subproject-A only. -tasks.dokkaHtmlPartial { - outputDirectory.set(layout.buildDirectory.dir("docs/partial")) -} -``` + dokka { + // The shared configuration goes here + } + ``` - - + 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. -Inside `./subproject-A/build.gradle`: +##### Apply the convention plugin to your subprojects -```groovy -apply plugin: 'org.jetbrains.dokka' +Apply the Dokka convention plugin across your subprojects by adding it to each subproject's `build.gradle.kts` +file: -// configuration for subproject-A only. -dokkaHtmlPartial { - outputDirectory.set(file("build/docs/partial")) +```kotlin +plugins { + id("dokka-convention") } ``` - - - -#### Parent project configuration +#### Multi-project builds with convention plugins -If you want to configure something which is universal across all documentation and does not belong to the -subprojects - in other words, it's a property of the parent project - you need to configure the -[`MultiModule`](#multimodule-tasks) tasks. +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 subprojects](#apply-the-convention-plugin-to-your-subprojects). - - +#### Parent project configuration -In the root `./build.gradle.kts` file: +In multi-project builds, you can configure settings that apply to the entire documentation in the root project. +This can include defining the output format, output directory, documentation subproject name, +aggregating documentation from all +subprojects, and other [configuration options](#configuration-options): ```kotlin plugins { id("org.jetbrains.dokka") version "%dokkaVersion%" } -tasks.dokkaHtmlMultiModule { - moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +dokka { + // Sets properties for the whole project + dokkaPublications.html { + moduleName.set("My Project") + outputDirectory.set(layout.buildDirectory.dir("docs/html")) + includes.from("README.md") + } + + dokkaSourceSets.configureEach { + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) + } } -``` - - +// Aggregates subproject documentation +dependencies { + dokka(project(":childProjectA")) + dokka(project(":childProjectB")) +} +``` -In the root `./build.gradle` file: +Additionally, each subproject can have its own `dokka {}` block if it needs custom configuration. +In the following example, the subproject applies the Dokka plugin, sets a custom subproject name, +and includes additional documentation from its `README.md` file: -```groovy +```kotlin +// subproject/build.gradle.kts plugins { - id 'org.jetbrains.dokka' version '%dokkaVersion%' + id("org.jetbrains.dokka") } -dokkaHtmlMultiModule { - moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER") +dokka { + dokkaPublications.html { + moduleName.set("Child Project A") + includes.from("README.md") + } } ``` - - - ## Configuration options Dokka has many configuration options to tailor your and your reader's experience. Below are some examples and detailed descriptions for each configuration section. You can also find an example -with [all configuration options](#complete-configuration) applied at the bottom of the page. +with [all configuration options](#complete-configuration) applied. See [Configuration examples](#configuration-examples) for more details on where to apply configuration blocks and how. ### General configuration -Here is an example of general configuration of any Dokka task, regardless of source set or package: +Here is an example of the general Dokka Gradle plugin configuration. Use the top-level `dokka {}` DSL configuration. + +In DGP, `dokkaPublications` is the central way to declare Dokka publication configurations. +The default publications +are [`html`](dokka-html.md) and [`javadoc`](dokka-javadoc.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 - -// 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 - // .. +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +dokka { + dokkaPublications.html { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(layout.buildDirectory.dir("dokka/html")) + failOnWarning.set(false) + suppressInheritedMembers.set(false) + offlineMode.set(false) + suppressObviousFunctions.set(true) + includes.from(project.files(), "packages.md", "extra.md") + + // 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")) + } + } + } } ``` @@ -720,23 +700,33 @@ tasks.withType().configureEach { ```groovy -import org.jetbrains.dokka.gradle.DokkaTask - -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType(DokkaTask.class) { - moduleName.set(project.name) - moduleVersion.set(project.version.toString()) - outputDirectory.set(file("build/dokka/$name")) - failOnWarning.set(false) - suppressObviousFunctions.set(true) - suppressInheritedMembers.set(false) - offlineMode.set(false) +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} - // .. - // source set configuration section - // .. +dokka { + dokkaPublications { + html { + // Sets general module information + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + + // Standard output directory for HTML documentation + outputDirectory.set(layout.buildDirectory.dir("dokka/html")) + + // Core Dokka options + failOnWarning.set(false) + suppressInheritedMembers.set(false) + offlineMode.set(false) + suppressObviousFunctions.set(true) + includes.from(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(file("$rootDir/docs/api/0.x")) + includes.from(layout.projectDirectory.file("README.md")) + } + } } ``` @@ -745,49 +735,41 @@ tasks.withType(DokkaTask.class) { -

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

-

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

+

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

Default: Gradle project name

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

Default: Gradle project version

 -

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

-

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

The directory where the generated documentation is stored.

+

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

+

Default: build/dokka/html

+

Output directory for additional files

+

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

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

This setting works well with reportUndocumented.

Default: false

 - -

Whether to suppress obvious functions.

-

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

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

    Default: true

    -

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

    @@ -809,11 +791,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 + subproject and package documentation. +

    +

    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.

    -

    Default: false

         @@ -826,29 +833,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 - -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier + +dokka { // .. - // general configuration section + // General configuration section // .. + // Source sets configuration dokkaSourceSets { - // configuration exclusive to the 'linux' source set + // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } + configureEach { suppress.set(false) displayName.set(name) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) reportUndocumented.set(false) skipEmptyPackages.set(true) skipDeprecated.set(false) @@ -856,24 +859,19 @@ tasks.withType().configureEach { jdkVersion.set(8) languageVersion.set("1.7") apiVersion.set("1.7") - noStdlibLink.set(false) - noJdkLink.set(false) - noAndroidSdkLink.set(false) - includes.from(project.files(), "packages.md", "extra.md") - platform.set(Platform.DEFAULT) sourceRoots.from(file("src")) classpath.from(project.files(), file("libs/dependency.jar")) samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") - + sourceLink { // Source link section } - externalDocumentationLink { - // External documentation link section - } perPackageOption { // Package options section } + externalDocumentationLinks { + // External documentation links section + } } } } @@ -883,29 +881,24 @@ tasks.withType().configureEach { ```groovy -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.Platform -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(DokkaTask.class) { +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier + +dokka { // .. - // general configuration section + // General configuration section // .. - + dokkaSourceSets { - // configuration exclusive to the 'linux' source set + // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets { named("native") } sourceRoots.from(file("linux/src")) } + configureEach { suppress.set(false) displayName.set(name) - documentedVisibilities.set([Visibility.PUBLIC]) + documentedVisibilities.set([VisibilityModifier.Public] as Set) // OR documentedVisibilities(VisibilityModifier.Public) reportUndocumented.set(false) skipEmptyPackages.set(true) skipDeprecated.set(false) @@ -913,24 +906,19 @@ tasks.withType(DokkaTask.class) { 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") + classpath.from(files(), file("libs/dependency.jar")) + samples.from(files(), "samples/Basic.kt", "samples/Advanced.kt") sourceLink { // Source link section } - externalDocumentationLink { - // External documentation link section - } perPackageOption { // Package options section } + externalDocumentationLinks { + // External documentation links section + } } } } @@ -953,13 +941,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 +960,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 +976,7 @@ tasks.withType(DokkaTask.class) {

    Whether to document declarations annotated with @Deprecated.

    -

    This can be configured on per-package basis.

    +

    This can be configured on a per-package basis.

    Default: false

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

    By default, it is deduced from languageVersion.

     - -

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

    -

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

    -

    Default: false

    -     - -

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

    -

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

    -

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

    -

    Default: false

    -     - - -

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

    -

    This is only relevant in Android projects, ignored otherwise.

    -

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

    -

    Default: false

    -     - -

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

    -

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

    -

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

    -     - -

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

    -

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

    -

    The source code roots to be analyzed and documented. @@ -1072,7 +1026,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 +1038,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,59 +1052,65 @@ 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") + } + } + } + } +} +``` + ```groovy -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(DokkaTask.class) { - // .. - // general configuration section - // .. - - dokkaSourceSets.configureEach { - // .. - // source set configuration section - // .. - - sourceLink { - localDirectory.set(file("src")) - remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src")) - remoteLineSuffix.set("#L") +dokka { + dokkaSourceSets { + main { + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl.set(new URI("https://github.com/your-repo")) + remoteLineSuffix.set("#L") + } } } } @@ -1189,36 +1154,51 @@ tasks.withType(DokkaTask.class) { +Since the source link configuration has [changed](https://docs.gradle.org/current/userguide/upgrading_version_8.html#deprecated_invalid_url_decoding), +use the `URI` class to specify the remote URL: + +```kotlin +remoteUrl.set(URI("https://github.com/your-repo")) + +// or + +remoteUrl("https://github.com/your-repo") +``` + +Additionally, +you can use two [utility functions](https://github.com/Kotlin/dokka/blob/220922378e6c68eb148fda2ec80528a1b81478c9/dokka-runners/dokka-gradle-plugin/src/main/kotlin/engine/parameters/DokkaSourceLinkSpec.kt#L82-L96) +for setting the URL: + +```kotlin +fun remoteUrl(@Language("http-url-reference") value: String): Unit = + remoteUrl.set(URI(value)) + +// and + +fun remoteUrl(value: Provider): Unit = + remoteUrl.set(value.map(::URI)) +``` + ### Package options -The `perPackageOption` configuration block allows setting some options for specific packages matched by `matchingRegex`. +The `perPackageOption` configuration block allows setting some options for specific packages matched by `matchingRegex`: ```kotlin -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType().configureEach { - // .. - // general configuration section - // .. - - dokkaSourceSets.configureEach { - // .. - // source set configuration section - // .. - - perPackageOption { - matchingRegex.set(".*api.*") - suppress.set(false) - skipDeprecated.set(false) - reportUndocumented.set(false) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) +dokka { + dokkaPublications.html { + dokkaSourceSets.configureEach { + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) + } } } } @@ -1228,28 +1208,20 @@ tasks.withType().configureEach { ```groovy -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask - -// Note: To configure multi-project builds, you need -// to configure Partial tasks of the subprojects. -// See "Configuration example" section of documentation. -tasks.withType(DokkaTask.class) { - // .. - // general configuration section - // .. - - dokkaSourceSets.configureEach { - // .. - // Source set configuration section - // .. - - perPackageOption { - matchingRegex.set(".*api.*") - suppress.set(false) - skipDeprecated.set(false) - reportUndocumented.set(false) - documentedVisibilities.set([Visibility.PUBLIC]) +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier + +dokka { + dokkaPublications { + html { + dokkaSourceSets.configureEach { + perPackageOption { + matchingRegex.set(".*api.*") + suppress.set(false) + skipDeprecated.set(false) + reportUndocumented.set(false) + documentedVisibilities.set([VisibilityModifier.Public] as Set) + } + } } } } @@ -1269,7 +1241,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 +1250,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 +1282,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") } } } @@ -1339,27 +1305,11 @@ tasks.withType().configureEach { ```groovy -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(DokkaTask.class) { - // .. - // general configuration section - // .. - +dokka { dokkaSourceSets.configureEach { - // .. - // source set configuration section - // .. - - externalDocumentationLink { - url.set(new URL("https://kotlinlang.org/api/kotlinx.serialization/")) - packageListUrl.set( - file("serialization.package.list").toURL() - ) + externalDocumentationLinks.register("example-docs") { + url.set(new URI("https://example.com/docs/")) + packageListUrl.set(new URI("https://example.com/docs/package-list")) } } } @@ -1387,7 +1337,7 @@ tasks.withType(DokkaTask.class) {

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

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

    @@ -1395,38 +1345,41 @@ tasks.withType(DokkaTask.class) { ### Complete configuration -Below you can see all possible configuration options applied at the same time. +Below you can see all possible configuration options applied at the same time: ```kotlin -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.Platform -import java.net.URL - -// 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) +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier + +plugins { + id("org.jetbrains.dokka") version "%dokkaVersion%" +} + +dokka { + dokkaPublications.html { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(layout.buildDirectory.dir("dokka/html")) + failOnWarning.set(false) + suppressInheritedMembers.set(false) + offlineMode.set(false) + suppressObviousFunctions.set(true) + includes.from(project.files(), "packages.md", "extra.md") + } dokkaSourceSets { + // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets{named("native")} sourceRoots.from(file("linux/src")) } + configureEach { suppress.set(false) displayName.set(name) - documentedVisibilities.set(setOf(Visibility.PUBLIC)) + documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR documentedVisibilities(VisibilityModifier.Public) reportUndocumented.set(false) skipEmptyPackages.set(true) skipDeprecated.set(false) @@ -1434,26 +1387,19 @@ tasks.withType().configureEach { jdkVersion.set(8) languageVersion.set("1.7") apiVersion.set("1.7") - noStdlibLink.set(false) - noJdkLink.set(false) - noAndroidSdkLink.set(false) - includes.from(project.files(), "packages.md", "extra.md") - platform.set(Platform.DEFAULT) sourceRoots.from(file("src")) classpath.from(project.files(), file("libs/dependency.jar")) samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt") - + sourceLink { - localDirectory.set(projectDir.resolve("src")) - remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src")) + localDirectory.set(file("src/main/kotlin")) + remoteUrl("https://example.com/src") remoteLineSuffix.set("#L") } - externalDocumentationLink { - url.set(URL("https://kotlinlang.org/api/core/kotlin-stdlib/")) - packageListUrl.set( - rootProject.projectDir.resolve("stdlib.package.list").toURL() - ) + externalDocumentationLinks { + url = URL("https://example.com/docs/") + packageListUrl = File("/path/to/package-list").toURI().toURL() } perPackageOption { @@ -1463,11 +1409,11 @@ tasks.withType().configureEach { reportUndocumented.set(false) documentedVisibilities.set( setOf( - Visibility.PUBLIC, - Visibility.PRIVATE, - Visibility.PROTECTED, - Visibility.INTERNAL, - Visibility.PACKAGE + VisibilityModifier.Public, + VisibilityModifier.Private, + VisibilityModifier.Protected, + VisibilityModifier.Internal, + VisibilityModifier.Package ) ) } @@ -1480,32 +1426,37 @@ tasks.withType().configureEach { ```groovy -import org.jetbrains.dokka.DokkaConfiguration.Visibility -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.Platform -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(DokkaTask.class) { - moduleName.set(project.name) - moduleVersion.set(project.version.toString()) - outputDirectory.set(file("build/dokka/$name")) - failOnWarning.set(false) - suppressObviousFunctions.set(true) - suppressInheritedMembers.set(false) - offlineMode.set(false) +import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier + +plugins { + id 'org.jetbrains.dokka' version '%dokkaVersion%' +} + +dokka { + dokkaPublications { + html { + moduleName.set(project.name) + moduleVersion.set(project.version.toString()) + outputDirectory.set(layout.buildDirectory.dir("dokka/html")) + failOnWarning.set(false) + suppressInheritedMembers.set(false) + offlineMode.set(false) + suppressObviousFunctions.set(true) + includes.from(files(), "packages.md", "extra.md") + } + } dokkaSourceSets { + // Example: Configuration exclusive to the 'linux' source set named("linux") { - dependsOn("native") + dependentSourceSets { named("native") } sourceRoots.from(file("linux/src")) } + configureEach { suppress.set(false) displayName.set(name) - documentedVisibilities.set([Visibility.PUBLIC]) + documentedVisibilities.set([VisibilityModifier.Public] as Set) reportUndocumented.set(false) skipEmptyPackages.set(true) skipDeprecated.set(false) @@ -1513,26 +1464,19 @@ tasks.withType(DokkaTask.class) { 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") + classpath.from(files(), file("libs/dependency.jar")) + samples.from(files(), "samples/Basic.kt", "samples/Advanced.kt") sourceLink { - localDirectory.set(file("src")) - remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src")) + localDirectory.set(file("src/main/kotlin")) + remoteUrl.set(new URI("https://example.com/src")) remoteLineSuffix.set("#L") } - externalDocumentationLink { - url.set(new URL("https://kotlinlang.org/api/core/kotlin-stdlib/")) - packageListUrl.set( - file("stdlib.package.list").toURL() - ) + externalDocumentationLinks { + url.set(new URI("https://example.com/docs/")) + packageListUrl.set(new File("/path/to/package-list").toURI().toURL()) } perPackageOption { @@ -1540,7 +1484,13 @@ tasks.withType(DokkaTask.class) { suppress.set(false) skipDeprecated.set(false) reportUndocumented.set(false) - documentedVisibilities.set([Visibility.PUBLIC]) + documentedVisibilities.set([ + VisibilityModifier.Public, + VisibilityModifier.Private, + VisibilityModifier.Protected, + VisibilityModifier.Internal, + VisibilityModifier.Package + ] as Set) } } } diff --git a/docs/topics/runners/dokka-maven.md b/docs/topics/runners/dokka-maven.md index 508eb767f3..0cef565355 100644 --- a/docs/topics/runners/dokka-maven.md +++ b/docs/topics/runners/dokka-maven.md @@ -56,7 +56,7 @@ By default, the Maven plugin for Dokka builds documentation in [HTML](dokka-html All other output formats are implemented as [Dokka plugins](dokka-plugins.md). In order to generate documentation in the desired format, you have to add it as a Dokka plugin to the configuration. -For example, to use the experimental [GFM](dokka-markdown.md#gfm) format, you have to add `gfm-plugin` artifact: +For example, to use the experimental [GFM](https://github.com/Kotlin/dokka/blob/8e5c63d035ef44a269b8c43430f43f5c8eebfb63/dokka-subprojects/plugin-gfm/README.md) format, you have to add `gfm-plugin` artifact: ```xml diff --git a/dokka-subprojects/plugin-gfm/README.md b/dokka-subprojects/plugin-gfm/README.md index 1d65c0f073..10d64924eb 100644 --- a/dokka-subprojects/plugin-gfm/README.md +++ b/dokka-subprojects/plugin-gfm/README.md @@ -1,17 +1,130 @@ # GFM plugin -The GFM plugin adds the ability to generate documentation in `GitHub Flavoured Markdown` format. It supports both -multi-module and multiplatform projects. +> This content 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). -The GFM plugin is shipped together with the Dokka Gradle Plugin, so you can start using it -right away with one of the following tasks: +The GFM plugin adds the ability to generate documentation in in [GitHub Flavored Markdown](https://github.github.com/gfm/) format. +It supports both multi-project builds and multiplatform projects. -* `dokkaGfm` - generate documentation for a single-project build or one specific module. -* `dokkaGfmMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. +This format gives you more freedom in terms of hosting documentation as the output can be embedded right into your +documentation website. -To use it with Maven or the CLI runner, you have to add it as a dependency. You can find it on -[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin) +## Gradle -GFM plugin comes built in with the Dokka Gradle plugin. You can also find it on +The GFM format is implemented as a Dokka plugin. 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() +``` + +Once you applied the plugin, you can run the following tasks: +* `dokkaGenerate` to generate documentation in [all available formats based on the applied plugins](dokka-gradle.md#configure-documentation-output-format). +* `dokkaGenerateMarkdown` to generate documentation only in Markdown format. + + +## Maven + +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 + + org.jetbrains.dokka + dokka-maven-plugin + ... + + + + org.jetbrains.dokka + gfm-plugin + %dokkaVersion% + + + + +``` + +After configuring this, running the `dokka:dokka` goal produces documentation in GFM format. + +For more information, see the Maven plugin documentation for [Other output formats](dokka-maven.md#other-output-formats). + +You can find the GFM plugin on [Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin). + +## CLI + +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`. + +Via [command line options](dokka-cli.md#run-with-command-line-options): + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar" \ + ... +``` + +Via [JSON configuration](dokka-cli.md#run-with-json-configuration): + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./gfm-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + +For more information, see the CLI runner's documentation for [Other output formats](dokka-cli.md#other-output-formats). \ No newline at end of file diff --git a/dokka-subprojects/plugin-jekyll/README.md b/dokka-subprojects/plugin-jekyll/README.md index 15ad907161..823e69c3bb 100644 --- a/dokka-subprojects/plugin-jekyll/README.md +++ b/dokka-subprojects/plugin-jekyll/README.md @@ -1,17 +1,111 @@ # Jekyll plugin -The Jekyll plugin adds the ability to generate documentation in `Jekyll Flavoured Markdown` format. It supports both -multi-module and multiplatform projects. +> This content 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). -The Jekyll plugin is shipped together with the Dokka Gradle Plugin, so you can start using it -right away with one of the following tasks: - -* `dokkaJekyll` - generate documentation for a single-project build or one specific module. -* `dokkaJekyllMultiModule` - generate documentation for a multi-module project, assemble it together and - generate navigation page/menu for all the modules. - -To use it with Maven or CLI runners, you have to add it as a dependency. You can find it on -[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin) +The Jekyll plugin adds the ability to generate documentation in [Jekyll Flavoured Markdown](https://jekyllrb.com/) format. +It supports both +multi-project builds and multiplatform projects. **This plugin is at its early stages**, so you may experience issues and encounter bugs. Feel free to [report](https://github.com/Kotlin/dokka/issues/new/choose) any errors you see. + +## Gradle + +The [Gradle plugin for Dokka](dokka-gradle.md) comes with the Jekyll output format included. + +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() +``` + +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). + +## Maven + +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 + + org.jetbrains.dokka + dokka-maven-plugin + ... + + + + org.jetbrains.dokka + jekyll-plugin + %dokkaVersion% + + + + +``` + +After configuring this, running the `dokka:dokka` goal to produce the documentation. + +For more information, see the Maven plugin's documentation for [Other output formats](dokka-maven.md#other-output-formats). +You can find the Jekyll plugin on +[Maven Central](https://mvnrepository.com/artifact/org.jetbrains.dokka/jekyll-plugin). + +## CLI + +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`: + +Via [command line options](dokka-cli.md#run-with-command-line-options): + +```Bash +java -jar dokka-cli-%dokkaVersion%.jar \ + -pluginsClasspath "./dokka-base-%dokkaVersion%.jar;...;./gfm-plugin-%dokkaVersion%.jar;./jekyll-plugin-%dokkaVersion%.jar" \ + ... +``` + +Via [JSON configuration](dokka-cli.md#run-with-json-configuration): + +```json +{ + ... + "pluginsClasspath": [ + "./dokka-base-%dokkaVersion%.jar", + "...", + "./gfm-plugin-%dokkaVersion%.jar", + "./jekyll-plugin-%dokkaVersion%.jar" + ], + ... +} +``` + +For more information, see the CLI runner's documentation for [Other output formats](dokka-cli.md#other-output-formats). + +You can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/dokka-subprojects/plugin-jekyll). \ No newline at end of file