Gradle
To generate documentation for a Gradle-based project, you can use the Gradle plugin for Dokka.
It comes with basic autoconfiguration for your project, has convenient Gradle tasks for generating documentation, and provides a great deal of 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.
The recommended way of applying the Gradle plugin for Dokka is with the plugins DSL:
plugins {
id("org.jetbrains.dokka") version "2.0.20"
}plugins {
id 'org.jetbrains.dokka' version '2.0.20'
}When documenting multi-project 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:
subprojects {
apply(plugin = "org.jetbrains.dokka")
}subprojects {
apply plugin: 'org.jetbrains.dokka'
}See Configuration examples if you are not sure where to apply Dokka.
note
Under the hood, Dokka uses the Kotlin Gradle plugin to perform autoconfiguration of source sets for which documentation is to be generated. Make sure to apply the Kotlin Gradle Plugin or configure source sets manually.
note
If you are using Dokka in a precompiled script plugin, you need to add the Kotlin Gradle plugin as a dependency for it to work properly.
If you cannot use the plugins DSL for some reason, you can use the legacy method of applying plugins.
The Gradle plugin for Dokka comes with HTML, Markdown and Javadoc output formats built in. It adds a number of tasks for generating documentation, both for single and multi-project builds.
Use the following tasks to build documentation for simple, single-project applications and libraries:
Task | Description |
|---|---|
| Generates documentation in HTML format. |
Task | Description |
|---|---|
| Generates documentation in GitHub Flavored Markdown format. |
| Generates documentation in Javadoc format. |
| Generates documentation in Jekyll compatible Markdown format. |
By default, generated documentation is located in the build/dokka/{format} directory of your project. The output location, among other things, can be configured.
For documenting multi-project builds, make sure that you apply the Gradle plugin for Dokka within subprojects that you want to generate documentation for, as well as in their parent project.
MultiModule tasks generate documentation for each subproject individually via Partial tasks, collect and process all outputs, and produce complete documentation with a common table of contents and resolved cross-project references.
Dokka creates the following tasks for parent projects automatically:
Task | Description |
|---|---|
| Generates multi-module documentation in HTML output format. |
Task | Description |
|---|---|
| Generates multi-module documentation in GitHub Flavored Markdown output format. |
| Generates multi-module documentation in Jekyll compatible Markdown output format. |
note
By default, you can find ready-to-use documentation under {parentProject}/build/dokka/{format}MultiModule directory.
Given a project with the following structure:
.
└── parentProject/
├── childProjectA/
│ └── demo/
│ └── ChildProjectAClass
└── childProjectB/
└── demo/
└── ChildProjectBClassThese pages are generated after running dokkaHtmlMultiModule:
See our multi-module project example for more details.
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 for each subproject (for example, dokkaHtml), and merges all outputs into a single virtual project.
The resulting documentation looks as if you have a single-project build that contains all declarations from the subprojects.
tip
Use the
dokkaJavadocCollectortask if you need to create Javadoc documentation for your multi-project build.
Given a project with the following structure:
.
└── parentProject/
├── childProjectA/
│ └── demo/
│ └── ChildProjectAClass
└── childProjectB/
└── demo/
└── ChildProjectBClassThese pages are generated after running dokkaHtmlCollector:
See our multi-module project example for more details.
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 task.
However, you can configure Partial tasks to customize Dokka for your subprojects.
warning
Output generated by
Partialtasks contains unresolved HTML templates and references, so it cannot be used on its own without post-processing done by the parent'sMultiModuletask.
note
If you want to generate documentation for a single subproject only, use single-project tasks. For example,
:subprojectName:dokkaHtml.
If you want to publish your library to a repository, you may need to provide a javadoc.jar file that contains API reference documentation of your library.
For example, if you want to publish to Maven Central, you must supply a javadoc.jar alongside your project. However, not all repositories have that rule.
The Gradle plugin for Dokka does not provide any way to do this out of the box, but it can be achieved with custom Gradle tasks. One for generating documentation in HTML format and another one for Javadoc format:
tasks.register<Jar>("dokkaHtmlJar") {
dependsOn(tasks.dokkaHtml)
from(tasks.dokkaHtml.flatMap { it.outputDirectory })
archiveClassifier.set("html-docs")
}
tasks.register<Jar>("dokkaJavadocJar") {
dependsOn(tasks.dokkaJavadoc)
from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
archiveClassifier.set("javadoc")
}tasks.register('dokkaHtmlJar', Jar.class) {
dependsOn(dokkaHtml)
from(dokkaHtml)
archiveClassifier.set("html-docs")
}
tasks.register('dokkaJavadocJar', Jar.class) {
dependsOn(dokkaJavadoc)
from(dokkaJavadoc)
archiveClassifier.set("javadoc")
}tip
If you publish your library to Maven Central, you can use services like javadoc.io to host your library's API documentation for free and without any setup. It takes documentation pages straight from the
javadoc.jar. It works well with the HTML format as demonstrated in this example.
Depending on the type of project that you have, the way you apply and configure Dokka differs slightly. However, configuration options themselves are the same, regardless of the type of your project.
For simple and flat projects with a single build.gradle.kts or build.gradle file found in the root of your project, see Single-project configuration.
For a more complex build with subprojects and multiple nested build.gradle.kts or build.gradle files, see Multi-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 platform:
.
├── build.gradle.kts
└── src
└── main
└── kotlin
└── HelloWorld.ktMultiplatform:
.
├── build.gradle.kts
└── src/
├── commonMain/
│ └── kotlin/
│ └── Common.kt
├── jvmMain/
│ └── kotlin/
│ └── JvmUtils.kt
└── nativeMain/
└── kotlin/
└── NativeUtils.ktSingle platform:
.
├── build.gradle
└── src
└── main
└── kotlin
└── HelloWorld.ktMultiplatform:
.
├── build.gradle
└── src/
├── commonMain/
│ └── kotlin/
│ └── Common.kt
├── jvmMain/
│ └── kotlin/
│ └── JvmUtils.kt
└── nativeMain/
└── kotlin/
└── NativeUtils.ktIn 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:
Inside ./build.gradle.kts:
plugins {
id("org.jetbrains.dokka") version "2.0.20"
}
tasks.dokkaHtml {
outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
}
tasks.dokkaGfm {
outputDirectory.set(layout.buildDirectory.dir("documentation/markdown"))
}Inside ./build.gradle:
plugins {
id 'org.jetbrains.dokka' version '2.0.20'
}
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:
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility
plugins {
id("org.jetbrains.dokka") version "2.0.20"
}
// Configure all single-project Dokka tasks at the same time,
// such as dokkaHtml, dokkaJavadoc and dokkaGfm.
tasks.withType<DokkaTask>().configureEach {
dokkaSourceSets.configureEach {
documentedVisibilities.set(
setOf(
Visibility.PUBLIC,
Visibility.PROTECTED,
)
)
perPackageOption {
matchingRegex.set(".*internal.*")
suppress.set(true)
}
}
}Inside ./build.gradle:
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility
plugins {
id 'org.jetbrains.dokka' version '2.0.20'
}
// 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)
}
}
}Gradle's multi-project builds 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:
.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A/
│ ├── build.gradle.kts
│ └── src/
│ └── main/
│ └── kotlin/
│ └── HelloFromA.kt
└── subproject-B/
├── build.gradle.kts
└── src/
└── main/
└── kotlin/
└── HelloFromB.kt.
├── build.gradle
├── settings.gradle
├── subproject-A/
│ ├── build.gradle
│ └── src/
│ └── main/
│ └── kotlin/
│ └── HelloFromA.kt
└── subproject-B/
├── build.gradle
└── src/
└── main/
└── kotlin/
└── HelloFromB.ktIn this case, there are multiple ways of applying and configuring Dokka.
To configure subprojects in a multi-project build, you need to configure Partial 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:
In the root ./build.gradle.kts:
import org.jetbrains.dokka.gradle.DokkaTaskPartial
plugins {
id("org.jetbrains.dokka") version "2.0.20"
}
subprojects {
apply(plugin = "org.jetbrains.dokka")
// configure only the HTML task
tasks.dokkaHtmlPartial {
outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
}
// configure all format tasks at once
tasks.withType<DokkaTaskPartial>().configureEach {
dokkaSourceSets.configureEach {
includes.from("README.md")
}
}
}In the root ./build.gradle:
import org.jetbrains.dokka.gradle.DokkaTaskPartial
plugins {
id 'org.jetbrains.dokka' version '2.0.20'
}
subprojects {
apply plugin: 'org.jetbrains.dokka'
// configure only the HTML task
dokkaHtmlPartial {
outputDirectory.set(file("build/docs/partial"))
}
// configure all format tasks at once
tasks.withType(DokkaTaskPartial.class) {
dokkaSourceSets.configureEach {
includes.from("README.md")
}
}
}Alternatively, you can apply and configure Dokka within subprojects individually.
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:
Inside ./subproject-A/build.gradle.kts:
apply(plugin = "org.jetbrains.dokka")
// configuration for subproject-A only.
tasks.dokkaHtmlPartial {
outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
}Inside ./subproject-A/build.gradle:
apply plugin: 'org.jetbrains.dokka'
// configuration for subproject-A only.
dokkaHtmlPartial {
outputDirectory.set(file("build/docs/partial"))
}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 tasks.
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:
In the root ./build.gradle.kts file:
plugins {
id("org.jetbrains.dokka") version "2.0.20"
}
tasks.dokkaHtmlMultiModule {
moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}In the root ./build.gradle file:
plugins {
id 'org.jetbrains.dokka' version '2.0.20'
}
dokkaHtmlMultiModule {
moduleName.set("WHOLE PROJECT NAME USED IN THE HEADER")
}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 applied at the bottom of the page.
See Configuration examples for more details on where to apply configuration blocks and how.
Here is an example of general configuration of any Dokka task, regardless of source set or package:
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>().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
// ..
}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)
// ..
// source set configuration section
// ..
}- moduleName
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
MultiModuletask, it is used as the project name.Default: Gradle project name
- moduleVersion
The module version. If set for a single-project build or a
MultiModuletask, it is used as the project version.Default: Gradle project version
- outputDirectory
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 thedokkaHtmlMultiModuletask, it isproject/buildDir/htmlMultiModule.- failOnWarning
Whether to fail documentation generation if Dokka has emitted a warning or an error. The process waits until all errors and warnings have been emitted first.
This setting works well with
reportUndocumented.Default:
false- suppressObviousFunctions
Whether to suppress obvious functions.
A function is considered to be obvious if it is:
Inherited from
kotlin.Any,Kotlin.Enum,java.lang.Objectorjava.lang.Enum, such asequals,hashCode,toString.Synthetic (generated by the compiler) and does not have any documentation, such as
dataClass.componentNordataClass.copy.
Default:
true- suppressInheritedMembers
Whether to suppress inherited members that aren't explicitly overridden in a given class.
Note: This can suppress functions such as
equals/hashCode/toString, but cannot suppress synthetic functions such asdataClass.componentNanddataClass.copy. UsesuppressObviousFunctionsfor that.Default:
false- offlineMode
Whether to resolve remote files/links over your network.
This includes package-lists used for generating external documentation links. For example, to make classes from the standard library clickable.
Setting this to
truecan significantly speed up build times in certain cases, 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
externalDocumentationLinkssection.Default:
false
Dokka allows configuring some options for Kotlin source sets:
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>().configureEach {
// ..
// general configuration section
// ..
dokkaSourceSets {
// configuration exclusive to the 'linux' source set
named("linux") {
dependsOn("native")
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set(setOf(Visibility.PUBLIC))
reportUndocumented.set(false)
skipEmptyPackages.set(true)
skipDeprecated.set(false)
suppressGeneratedFiles.set(true)
jdkVersion.set(8)
languageVersion.set("1.7")
apiVersion.set("1.7")
noStdlibLink.set(false)
noJdkLink.set(false)
noAndroidSdkLink.set(false)
includes.from(project.files(), "packages.md", "extra.md")
platform.set(Platform.DEFAULT)
sourceRoots.from(file("src"))
classpath.from(project.files(), file("libs/dependency.jar"))
samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")
sourceLink {
// Source link section
}
externalDocumentationLink {
// External documentation link section
}
perPackageOption {
// Package options section
}
}
}
}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) {
// ..
// general configuration section
// ..
dokkaSourceSets {
// configuration exclusive to the 'linux' source set
named("linux") {
dependsOn("native")
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set([Visibility.PUBLIC])
reportUndocumented.set(false)
skipEmptyPackages.set(true)
skipDeprecated.set(false)
suppressGeneratedFiles.set(true)
jdkVersion.set(8)
languageVersion.set("1.7")
apiVersion.set("1.7")
noStdlibLink.set(false)
noJdkLink.set(false)
noAndroidSdkLink.set(false)
includes.from(project.files(), "packages.md", "extra.md")
platform.set(Platform.DEFAULT)
sourceRoots.from(file("src"))
classpath.from(project.files(), file("libs/dependency.jar"))
samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")
sourceLink {
// Source link section
}
externalDocumentationLink {
// External documentation link section
}
perPackageOption {
// Package options section
}
}
}
}- displayName
The display name used to refer to this source set.
The name is used both externally (for example, as source set name visible to documentation readers) and internally (for example, for logging messages of
reportUndocumented).By default, the value is deduced from information provided by the Kotlin Gradle plugin.
- documentedVisibilities
The set of visibility modifiers that should be documented.
This can be used if you want to document
protected/internal/privatedeclarations, as well as if you want to excludepublicdeclarations and only document internal API.This can be configured on per-package basis.
Default:
DokkaConfiguration.Visibility.PUBLIC- reportUndocumented
Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they have been filtered by
documentedVisibilitiesand other filters.This setting works well with
failOnWarning.This can be configured on per-package basis.
Default:
false- skipEmptyPackages
Whether to skip packages that contain no visible declarations after various filters have been applied.
For example, if
skipDeprecatedis set totrueand your package contains only deprecated declarations, it is considered to be empty.Default:
true- skipDeprecated
Whether to document declarations annotated with
@Deprecated.This can be configured on per-package basis.
Default:
false- suppressGeneratedFiles
Whether to document/analyze generated files.
Generated files are expected to be present under the
{project}/{buildDir}/generateddirectory.If set to
true, it effectively adds all files from that directory to thesuppressedFilesoption, so you can configure it manually.Default:
true- jdkVersion
The JDK version to use when generating external documentation links for Java types.
For example, if you use
java.util.UUIDin some public declaration signature, and this option is set to8, Dokka generates an external documentation link to JDK 8 Javadocs for it.Default: JDK 8
- languageVersion
The Kotlin language version used for setting up analysis and @sample environment.
By default, the latest language version available to Dokka's embedded compiler is used.
- apiVersion
The Kotlin API version used for setting up analysis and @sample environment.
By default, it is deduced from
languageVersion.- noStdlibLink
Whether to generate external documentation links that lead to the API reference documentation of Kotlin's standard library.
Note: Links are generated when
noStdLibLinkis set tofalse.Default:
false- noJdkLink
Whether to generate external documentation links to JDK's Javadocs.
The version of JDK Javadocs is determined by the
jdkVersionoption.Note: Links are generated when
noJdkLinkis set tofalse.Default:
false- includes
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.
- platform
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.
- sourceRoots
The source code roots to be analyzed and documented. Acceptable inputs are directories and individual
.kt/.javafiles.By default, source roots are deduced from information provided by the Kotlin Gradle plugin.
- classpath
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
.jarand.klibfiles.By default, classpath is deduced from information provided by the Kotlin Gradle plugin.
- samples
A list of directories or files that contain sample functions which are referenced via the @sample KDoc tag.
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).
This helps readers to find the source code for each declaration.
For an example, see the documentation for the count() function in kotlinx.coroutines.
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>().configureEach {
// ..
// general configuration section
// ..
dokkaSourceSets.configureEach {
// ..
// source set configuration section
// ..
sourceLink {
localDirectory.set(projectDir.resolve("src"))
remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
remoteLineSuffix.set("#L")
}
}
}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")
}
}
}- localDirectory
The path to the local source directory. The path must be relative to the root of the current project.
- remoteUrl
The URL of the source code hosting service that can be accessed by documentation readers, like GitHub, GitLab, Bitbucket, etc. This URL is used to generate source code links of declarations.
- remoteLineSuffix
The suffix used to append the source code line number to the URL. This helps readers navigate not only to the file, but to the specific line number of the declaration.
The number itself is appended to the specified suffix. For example, if this option is set to
#Land the line number is 10, the resulting URL suffix is#L10.Suffixes used by popular services:
GitHub:
#LGitLab:
#LBitbucket:
#lines-
Default:
#L
The perPackageOption configuration block allows setting some options for specific packages matched by matchingRegex.
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>().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))
}
}
}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])
}
}
}- skipDeprecated
Whether to document declarations annotated with
@Deprecated.This can be configured on source set level.
Default:
false- reportUndocumented
Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they have been filtered by
documentedVisibilitiesand other filters.This setting works well with
failOnWarning.This can be configured on source set level.
Default:
false- documentedVisibilities
The set of visibility modifiers that should be documented.
This can be used if you want to document
protected/internal/privatedeclarations within this package, as well as if you want to excludepublicdeclarations and only document internal API.This can be configured on source set level.
Default:
DokkaConfiguration.Visibility.PUBLIC
The externalDocumentationLink 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 documentation, as if they are unresolved. However, since the API reference documentation for kotlinx.serialization is built by Dokka and is published on kotlinlang.org, you can 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.
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>().configureEach {
// ..
// general configuration section
// ..
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()
)
}
}
}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
// ..
externalDocumentationLink {
url.set(new URL("https://kotlinlang.org/api/kotlinx.serialization/"))
packageListUrl.set(
file("serialization.package.list").toURL()
)
}
}
}- url
The root URL of documentation to link to. It must contain a trailing slash.
Dokka does its best to automatically find
package-listfor the given URL, and link declarations together.If automatic resolution fails or if you want to use locally cached files instead, consider setting the
packageListUrloption.
Below you can see all possible configuration options applied at the same time.
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>().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)
dokkaSourceSets {
named("linux") {
dependsOn("native")
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set(setOf(Visibility.PUBLIC))
reportUndocumented.set(false)
skipEmptyPackages.set(true)
skipDeprecated.set(false)
suppressGeneratedFiles.set(true)
jdkVersion.set(8)
languageVersion.set("1.7")
apiVersion.set("1.7")
noStdlibLink.set(false)
noJdkLink.set(false)
noAndroidSdkLink.set(false)
includes.from(project.files(), "packages.md", "extra.md")
platform.set(Platform.DEFAULT)
sourceRoots.from(file("src"))
classpath.from(project.files(), file("libs/dependency.jar"))
samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")
sourceLink {
localDirectory.set(projectDir.resolve("src"))
remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
remoteLineSuffix.set("#L")
}
externalDocumentationLink {
url.set(URL("https://kotlinlang.org/api/core/kotlin-stdlib/"))
packageListUrl.set(
rootProject.projectDir.resolve("stdlib.package.list").toURL()
)
}
perPackageOption {
matchingRegex.set(".*api.*")
suppress.set(false)
skipDeprecated.set(false)
reportUndocumented.set(false)
documentedVisibilities.set(
setOf(
Visibility.PUBLIC,
Visibility.PRIVATE,
Visibility.PROTECTED,
Visibility.INTERNAL,
Visibility.PACKAGE
)
)
}
}
}
}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)
dokkaSourceSets {
named("linux") {
dependsOn("native")
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set([Visibility.PUBLIC])
reportUndocumented.set(false)
skipEmptyPackages.set(true)
skipDeprecated.set(false)
suppressGeneratedFiles.set(true)
jdkVersion.set(8)
languageVersion.set("1.7")
apiVersion.set("1.7")
noStdlibLink.set(false)
noJdkLink.set(false)
noAndroidSdkLink.set(false)
includes.from(project.files(), "packages.md", "extra.md")
platform.set(Platform.DEFAULT)
sourceRoots.from(file("src"))
classpath.from(project.files(), file("libs/dependency.jar"))
samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")
sourceLink {
localDirectory.set(file("src"))
remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src"))
remoteLineSuffix.set("#L")
}
externalDocumentationLink {
url.set(new URL("https://kotlinlang.org/api/core/kotlin-stdlib/"))
packageListUrl.set(
file("stdlib.package.list").toURL()
)
}
perPackageOption {
matchingRegex.set(".*api.*")
suppress.set(false)
skipDeprecated.set(false)
reportUndocumented.set(false)
documentedVisibilities.set([Visibility.PUBLIC])
}
}
}
}Thanks for your feedback!