Using the Gradle plugin¶
Important
If you are upgrading from 0.10.x to a current release of Dokka, please have a look at our migration guide
The preferred way is to use plugins
block. Since Dokka is currently not published to the Gradle plugin portal,
you not only need to add dokka
to the build.gradle.kts
file, but you also need to modify the settings.gradle.kts
file:
build.gradle.kts:
plugins {
id("org.jetbrains.dokka") version "1.4.30"
}
repositories {
jcenter() // or maven(url="https://dl.bintray.com/kotlin/dokka")
}
settings.gradle.kts:
pluginManagement {
repositories {
gradlePluginPortal()
jcenter()
}
}
You can also use the legacy plugin application method with buildscript
block.
Note that by using the buildscript
way type-safe accessors are not available in Gradle Kotlin DSL,
eg. you'll have to use named<DokkaTask>("dokkaHtml")
instead of dokkaHtml
:
buildscript {
repositories {
jcenter()
}
dependencies {
classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}")
}
}
repositories {
jcenter() // or maven(url="https://dl.bintray.com/kotlin/dokka")
}
apply(plugin="org.jetbrains.dokka")
The plugin adds dokkaHtml
, dokkaJavadoc
, dokkaGfm
and dokkaJekyll
tasks to the project.
Each task corresponds to one output format, so you should run dokkaGfm
when you want to have a documentation in GFM
format.
Output formats are explained in the introduction
If you encounter any problems when migrating from older versions of Dokka, please see the FAQ.
Minimal configuration (with custom output directory only):
Kotlin
tasks.dokkaHtml.configure {
outputDirectory.set(buildDir.resolve("dokka"))
}
Groovy
tasks.named("dokkaHtml") {
outputDirectory.set(buildDir.resolve("dokka"))
}
Configuration options¶
Dokka documents single-platform as well as multi-platform projects. Most of the configuration options are set per one source set. The available configuration options for are shown below:
dokkaHtml {
outputDirectory.set(buildDir.resolve("dokka"))
// Set module name displayed in the final output
moduleName.set("moduleName")
// Use default or set to custom path to cache directory
// to enable package-list caching
// When this is set to default, caches are stored in $USER_HOME/.cache/dokka
cacheRoot.set(file("default"))
// Suppress obvious functions like default toString or equals. Defaults to true
suppressObviousFunctions.set(false)
dokkaSourceSets {
configureEach { // Or source set name, for single-platform the default source sets are `main` and `test`
// Used when configuring source sets manually for declaring which source sets this one depends on
dependsOn("otherSourceSetName")
// Used to remove a source set from documentation, test source sets are suppressed by default
suppress.set(false)
// Used to prevent resolving package-lists online. When this option is set to true, only local files are resolved
offlineMode.set(false)
// Use to include or exclude non public members
includeNonPublic.set(false)
// Do not output deprecated members. Applies globally, can be overridden by packageOptions
skipDeprecated.set(false)
// Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
reportUndocumented.set(true)
// Do not create index pages for empty packages
skipEmptyPackages.set(true)
// This name will be shown in the final output
displayName.set("JVM")
// Platform used for code analysis. See the "Platforms" section of this readme
platform.set(org.jetbrains.dokka.Platform.jvm)
// Property used for manual addition of files to the classpath
// This property does not override the classpath collected automatically but appends to it
classpath.from(file("libs/dependency.jar"))
// List of files with module and package documentation
// https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
includes.from("packages.md", "extra.md")
// List of files or directories containing sample code (referenced with @sample tags)
samples.from("samples/basic.kt", "samples/advanced.kt")
// By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them
// Repeat for multiple sourceRoots
sourceRoot.from(file("src"))
// Specifies the location of the project source code on the Web.
// If provided, Dokka generates "source" links for each declaration.
// Repeat for multiple mappings
sourceLink {
// Unix based directory relative path to the root of the project (where you execute gradle respectively).
localDirectory.set(file("src/main/kotlin"))
// URL showing where the source code can be accessed through the web browser
remoteUrl.set(java.net.URL(
"https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"))
// Suffix which is used to append the line number to the URL. Use #L for GitHub
remoteLineSuffix.set("#L")
}
// Used for linking to JDK documentation
jdkVersion.set(8)
// Disable linking to online kotlin-stdlib documentation
noStdlibLink.set(false)
// Disable linking to online JDK documentation
noJdkLink.set(false)
// Disable linking to online Android documentation (only applicable for Android projects)
noAndroidSdkLink.set(false)
// Allows linking to documentation of the project"s dependencies (generated with Javadoc or Dokka)
// Repeat for multiple links
externalDocumentationLink {
// Root URL of the generated documentation to link with. The trailing slash is required!
url = URL("https://example.com/docs/")
// If package-list file is located in non-standard location
// packageListUrl = URL("file:///home/user/localdocs/package-list")
}
// Allows to customize documentation generation options on a per-package basis
// Repeat for multiple packageOptions
// If multiple packages match the same matchingRegex, the longuest matchingRegex will be used
perPackageOption {
matchingRegex.set("kotlin($|\\.).*") // will match kotlin and all sub-packages of it
// All options are optional, default values are below:
skipDeprecated.set(false)
reportUndocumented.set(true) // Emit warnings about not documented members
includeNonPublic.set(false)
}
// Suppress a package
perPackageOption {
matchingRegex.set(".*\.internal.*") // will match all .internal packages and sub-packages
suppress.set(true)
}
}
// Configures a plugin separately from the global configuration
pluginConfiguration<PluginClass, ConfigurationClass>{
// values
}
}
}
Multiplatform¶
Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects you should assume that Dokka's source sets correspond to Kotlin plugin's source sets. All source sets are by default registered and configured automatically although test source sets are suppressed
Kotlin
kotlin { // Kotlin Multiplatform plugin configuration
jvm()
js("customName")
}
tasks.withType<DokkaTask>().configureEach {
// custom output directory
outputDirectory.set(buildDir.resolve("dokka"))
// path to project documentation to display on all modules page
includes.from(listOf(file("project_description.md")))
dokkaSourceSets {
named("customNameMain") { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically
includes.from("packages.md", "extra.md")
samples.from("samples/basic.kt", "samples/advanced.kt")
}
register("differentName") { // Different name, so source roots must be passed explicitly
displayName.set("JVM")
platform.set(org.jetbrains.dokka.Platform.jvm)
sourceRoots.from(kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs)
sourceRoots.from(kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs)
}
}
}
Note
If you want to share the configuration between source sets, you can use Gradle's configureEach
Applying plugins¶
Dokka plugin creates Gradle configuration for each output format in the form of dokka${format}Plugin
:
dependencies {
dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.30")
}
You can also create a custom Dokka task and add plugins directly inside:
val customDokkaTask by creating(DokkaTask::class) {
dependencies {
plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.30")
}
}
Important
Please note that dokkaJavadoc
task will properly document only single jvm
source set
To generate the documentation, use the appropriate dokka${format}
Gradle task:
./gradlew dokkaHtml
Some plugins can be configured separately using a plugin class and configuration class. For example:
pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
customAssets = listOf(file("<path to asset>"))
customStyleSheets = listOf(file("<path to custom stylesheet>"))
}
Keep in mind, that this only works when using a buildscript (with the configured plugin on classpath) since it is not possible to import plugin's class without it.
If you don't want to use a buildscript or use Kotlin version lower than 1.3.50 you can achieve the same behaviour manually:
pluginsMapConfiguration.set(mapOf("<fully qualified plugin's name>" to """<json configuration>"""))
Android¶
Important
Make sure you apply Dokka after com.android.library
and kotlin-android
.
buildscript {
repositories {
jcenter()
}
dependencies {
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}")
classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}")
}
}
repositories {
jcenter()
}
apply(plugin= "com.android.library")
apply(plugin= "kotlin-android")
apply(plugin= "org.jetbrains.dokka")
dokkaHtml.configure {
dokkaSourceSets {
named("main") {
noAndroidSdkLink.set(false)
}
}
}
Multi-module projects¶
For documenting Gradle multi-module projects, you can use dokka${format}MultiModule
tasks.
tasks.dokkaHtmlMultiModule.configure {
outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput"))
}
DokkaMultiModule
depends on all Dokka tasks in the subprojects, runs them, and creates a toplevel page
with links to all generated (sub)documentations
Example project¶
Please see the Dokka Gradle example project for an example.