antohaby/dokkatoo

Dokkatoo is a Gradle plugin that generates documentation for your Kotlin projects.

Under the hood it uses Dokka, the API documentation engine for Kotlin.

Why Dokkatoo?

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

Status

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.

Usage

Dokkatoo is published on the Gradle Plugin Portal.

Quick start

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/

Configuring Dokkatoo

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)
  }
}

Combining subprojects

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 :dokkatooGeneratePublicationHtml

Dokkatoo 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).

Migrating from Dokka Gradle Plugin

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.

Apply both Dokka Gradle Plugin and Dokkatoo

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 releases

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()
      }
    }
  }
}

antohaby / dokkatoo