Dokkatoo is a Gradle plugin that generates documentation for your Kotlin projects.
Under the hood it uses Dokka, the API documentation engine for Kotlin.
If Dokka already has a Gradle plugin, then what is Dokkatoo for?
Dokkatoo has a number of improvements over the existing Dokka Gradle Plugin:
- Compatible with Gradle Build Cache
- Compatible with Gradle Configuration Cache
- Safe cross-project sharing and aggregation
- Parallel execution
Dokkatoo has basic functionality, and can generate documentation for single-projects and multimodule projects.
Be aware that many things are untested, broken, and undocumented. Please create an issue if something is not as you'd expect, or like.
Dokkatoo is published on the Gradle Plugin Portal.
-
Apply the appropriate plugin for any formats you'd like to generate.
For example, HTML and Javadoc
// build.gradle.kts plugins { // only generate HTML and Javadoc id("dev.adamko.dokkatoo-html") version "$dokkatooVersion" id("dev.adamko.dokkatoo-javadoc") version "$dokkatooVersion" //id("dev.adamko.dokkatoo-gfm") version "$dokkatooVersion" //id("dev.adamko.dokkatoo-jekyll") version "$dokkatooVersion" }
Or all formats
// build.gradle.kts plugins { // generate all formats - HTML, Jekyll, Javadoc, and GFM (GitHub Flavoured Markdown) id("dev.adamko.dokkatoo") version "$dokkatooVersion" }
-
Run the generation task
./gradlew dokkatooGenerate
-
View the results in
./build/dokka/
Once the Dokkatoo plugin is applied to a project, it can be configuring using the dokkatoo {} DSL.
Here is an example - it is not exhaustive and does not cover all functionality.
// build.gradle.kts
import dev.adamko.dokkatoo.dokka.plugins.DokkaHtmlPluginParameters
plugins {
id("dev.adamko.dokkatoo-html") version "$dokkatooVersion"
}
dokkatoo {
moduleName.set("Basic Project")
dokkatooSourceSets.configureEach {
documentedVisibilities(
VisibilityModifier.PUBLIC,
VisibilityModifier.PROTECTED,
)
suppressedFiles.from(file("src/main/kotlin/it/suppressedByPath"))
perPackageOption {
matchingRegex.set("it.suppressedByPackage.*")
suppress.set(true)
}
perPackageOption {
matchingRegex.set("it.overriddenVisibility.*")
documentedVisibilities(
DokkaConfiguration.Visibility.PRIVATE
)
}
}
pluginsConfiguration.html {
customStyleSheets.from(
"./customResources/logo-styles.css",
"./customResources/custom-style-to-add.css",
)
customAssets.from(
"./customResources/custom-resource.svg",
)
footerMessage.set("(C) The Owner")
}
dokkatooPublications.configureEach {
suppressObviousFunctions.set(true)
suppressObviousFunctions.set(false)
}
}Dokkatoo can aggregate documentation from subprojects.
To do this, apply the Dokkatoo plugin in all subprojects that should be documented.
In the aggregating project, depend on the other subprojects.
// build.gradle.kts
plugins {
id("dev.adamko.dokkatoo-html") version "$dokkatooVersion"
}
dependencies {
// aggregate both subproject-hello and subproject-world
// the subprojects must also have Dokkatoo applied
dokkatoo(projects(":subproject-hello"))
dokkatoo(projects(":subproject-world"))
// This is required at the moment, see https://github.com/adamko-dev/dokkatoo/issues/14
dokkatooPluginHtml(
dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
"org.jetbrains.dokka:all-modules-page-plugin:$dokkaVersion"
}
)
}Run the Dokkatoo generation task.
./gradlew :dokkatooGeneratePublicationHtmlDokkatoo will then generate documentation into ./build/dokka/
To improve performance only run the task in the aggregating project by prefixing the task name with
the subproject path (or : if aggregating in the root project).
Dokkatoo is not a drop-in replacement for the Dokka Gradle Plugin, and requires migration.
When Dokkatoo matures, a guide will be made available. For now, check the example projects for comparative examples.
For help in migrating from the Dokka Gradle Plugin to Dokkatoo, you can still apply both plugins - just make sure to update the Dokkatoo output directory!
// build.gradle.kts
plugins {
id("org.jetbrains.dokka") version "$dokkaVersion"
id("dev.adamko.dokkatoo-html") version "$dokkatooVersion"
}
dokkatoo {
// update the output directory, so it doesn't clash with the Dokka plugin!
dokkatooPublicationDirectory.set(layout.buildDirectory.dir("dokkatoo"))
}Snapshot versions of Dokkatoo are available. They are published to a GitHub branch, which must be added as a custom Gradle Plugin repository
// settings.gradle.kts
pluginManagement {
repositories {
gradlePluginPortal()
mavenCentral()
// add the Dokkatoo snapshot repository
maven("https://raw.githubusercontent.com/adamko-dev/dokkatoo/artifacts/m2/") {
name = "Dokkatoo Snapshots"
// only include Dokkatoo snapshots
mavenContent {
includeGroup("dev.adamko.dokkatoo")
includeGroup("dev.adamko.dokkatoo-html")
includeGroup("dev.adamko.dokkatoo-javadoc")
includeGroup("dev.adamko.dokkatoo-jekyll")
includeGroup("dev.adamko.dokkatoo-markdown")
snapshotsOnly()
}
}
}
}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent