Skip to content

Update Gradle Dokka configuration to make sure "source" button is visible in all API docs #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 1, 2023
Merged

Update Gradle Dokka configuration to make sure "source" button is visible in all API docs #244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions build-logic/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,6 @@ repositories {

dependencies {
implementation(libs.kotlin.gradle.plugin)
implementation(libs.dokka.gradle.plugin)
implementation(libs.animalsniffer.gradle.plugin)
}
30 changes: 30 additions & 0 deletions build-logic/src/main/kotlin/kotlinx/io/conventions/kotlinx-io-dokka.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/*
* Copyright 2017-2023 JetBrains s.r.o. and respective authors and developers.
* Use of this source code is governed by the Apache 2.0 license that can be found in the LICENCE file.
*/

import org.jetbrains.dokka.gradle.*
import java.net.*

plugins {
id("org.jetbrains.dokka")
}

tasks.withType<DokkaTaskPartial>().configureEach {
dokkaSourceSets.configureEach {
includes.from("Module.md")

if (name.endsWith("Main")) {
sourceLink {
// sources are located in projectDir/PLATFORM/src
// where the PLATFORM could be jvm, js, darwin, etc.
// configuration happens in kotlinx-io-multiplatform.gradle.kts:KotlinSourceSet.configureSourceSet
val platform = name.dropLast(4)
val relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
localDirectory.set(projectDir.resolve("$platform/src"))
remoteUrl.set(URL("https://github.com/kotlin/kotlinx-io/tree/master/$relPath/$platform/src"))
remoteLineSuffix.set("#L")
}
}
}
}
4 changes: 1 addition & 3 deletions bytestring/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ import org.jetbrains.dokka.gradle.DokkaTaskPartial
plugins {
id("kotlinx-io-multiplatform")
id("kotlinx-io-publish")
id("kotlinx-io-dokka")
id("kotlinx-io-android-compat")
alias(libs.plugins.kover)
alias(libs.plugins.dokka)
}

kotlin {
Expand All @@ -30,8 +30,6 @@ kotlin {

tasks.withType<DokkaTaskPartial>().configureEach {
dokkaSourceSets.configureEach {
includes.from("Module.md")

perPackageOption {
suppress.set(true)
matchingRegex.set(".*unsafe.*")
Expand Down
4 changes: 1 addition & 3 deletions core/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ import org.jetbrains.dokka.gradle.DokkaTaskPartial
plugins {
id("kotlinx-io-multiplatform")
id("kotlinx-io-publish")
id("kotlinx-io-dokka")
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just in case: can we also replace alias(libs.plugins.dokka) with id("kotlinx-io-dokka") in the root build.gradle.kts? It seems like everything works fine afterward, but maybe I'm missing something.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really, as root module doesn't have any sources, and so those changes have no affect for root module, also only one task from root module is executed from Dokka - dokkaHtmlMultimodule and it's just an aggregate task

So I would suggest to leave this as is:

  • kotlinx-io-dokka for subprojects, where documentation building can be customised consistently
  • plain dokka in root (aggregate) project, where documentation aggregation can be customised

It's similar to how kover works - there are leaf projects and there is an aggregate project (only that Dokka DSL isn't that good, yet :) )

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanation!

id("kotlinx-io-android-compat")
alias(libs.plugins.kover)
alias(libs.plugins.dokka)
}

kotlin {
Expand Down Expand Up @@ -59,8 +59,6 @@ kotlin {

tasks.withType<DokkaTaskPartial>().configureEach {
dokkaSourceSets.configureEach {
includes.from("Module.md")

samples.from(
"common/test/samples/rawSinkSample.kt",
"common/test/samples/rawSourceSample.kt",
Expand Down
1 change: 1 addition & 0 deletions gradle/libs.versions.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ animalsniffer = "1.7.1"

kotlinx-benchmark-runtime = { group = "org.jetbrains.kotlinx", name = "kotlinx-benchmark-runtime", version.ref = "benchmark" }
kotlin-gradle-plugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
dokka-gradle-plugin = { group = "org.jetbrains.dokka", name = "dokka-gradle-plugin", version.ref = "dokka" }
kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
animalsniffer-gradle-plugin = { group = "ru.vyarus", name = "gradle-animalsniffer-plugin", version.ref = "animalsniffer" }

Expand Down