From 5594b8fd5fd9a377d122622020c2cfd0aa5c234f Mon Sep 17 00:00:00 2001 From: Adam <897017+aSemy@users.noreply.github.com> Date: Tue, 15 Aug 2023 15:15:02 +0200 Subject: [PATCH 1/2] add util function for adding external doc link --- .../dokkatoo-plugin/api/dokkatoo-plugin.api | 2 ++ .../dokka/parameters/DokkaSourceSetSpec.kt | 29 +++++++++++++++++-- .../builders/DokkaSourceSetBuilderTest.kt | 16 +++++++--- .../kotlin/samWithReceiverWorkarounds.kt | 8 +++++ 4 files changed, 48 insertions(+), 7 deletions(-) diff --git a/modules/dokkatoo-plugin/api/dokkatoo-plugin.api b/modules/dokkatoo-plugin/api/dokkatoo-plugin.api index d767d2ec..1a0b5ec1 100644 --- a/modules/dokkatoo-plugin/api/dokkatoo-plugin.api +++ b/modules/dokkatoo-plugin/api/dokkatoo-plugin.api @@ -137,6 +137,8 @@ public final class dev/adamko/dokkatoo/dokka/parameters/DokkaSourceSetIdSpec$Com } public abstract class dev/adamko/dokkatoo/dokka/parameters/DokkaSourceSetSpec : dev/adamko/dokkatoo/dokka/parameters/HasConfigurableVisibilityModifiers, java/io/Serializable, org/gradle/api/Named, org/gradle/api/plugins/ExtensionAware { + public final fun externalDocumentationLink (Ljava/net/URI;Lorg/gradle/api/Action;)Ldev/adamko/dokkatoo/dokka/parameters/DokkaExternalDocumentationLinkSpec; + public static synthetic fun externalDocumentationLink$default (Ldev/adamko/dokkatoo/dokka/parameters/DokkaSourceSetSpec;Ljava/net/URI;Lorg/gradle/api/Action;ILjava/lang/Object;)Ldev/adamko/dokkatoo/dokka/parameters/DokkaExternalDocumentationLinkSpec; public abstract fun getAnalysisPlatform ()Lorg/gradle/api/provider/Property; public abstract fun getApiVersion ()Lorg/gradle/api/provider/Property; public abstract fun getClasspath ()Lorg/gradle/api/file/ConfigurableFileCollection; diff --git a/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt b/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt index c15c5bf8..90506de1 100644 --- a/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt +++ b/modules/dokkatoo-plugin/src/main/kotlin/dokka/parameters/DokkaSourceSetSpec.kt @@ -1,14 +1,22 @@ package dev.adamko.dokkatoo.dokka.parameters import dev.adamko.dokkatoo.dokka.parameters.DokkaSourceSetIdSpec.Companion.dokkaSourceSetIdSpec -import dev.adamko.dokkatoo.internal.* +import dev.adamko.dokkatoo.internal.DokkatooInternalApi +import dev.adamko.dokkatoo.internal.adding +import dev.adamko.dokkatoo.internal.domainObjectContainer import java.io.Serializable +import java.net.URI import javax.inject.Inject -import org.gradle.api.* +import org.gradle.api.Action +import org.gradle.api.DomainObjectSet +import org.gradle.api.Named +import org.gradle.api.NamedDomainObjectContainer import org.gradle.api.file.ConfigurableFileCollection import org.gradle.api.model.ObjectFactory import org.gradle.api.plugins.ExtensionAware -import org.gradle.api.provider.* +import org.gradle.api.provider.Property +import org.gradle.api.provider.Provider +import org.gradle.api.provider.SetProperty import org.gradle.api.tasks.* import org.gradle.kotlin.dsl.* @@ -351,6 +359,21 @@ constructor( ) } + /** + * Add a new external documentation link to [externalDocumentationLinks]. + * + * @see externalDocumentationLinks + * @see DokkaExternalDocumentationLinkSpec + */ + fun externalDocumentationLink( + url: URI, + configure: Action = Action {} + ): DokkaExternalDocumentationLinkSpec = + externalDocumentationLinks.create(url.toASCIIString()) { + this.url.set(url) + configure.execute(this) + } + /** * Action for configuring package options, appending to [perPackageOptions]. * diff --git a/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt b/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt index 81d349e5..be1258d6 100644 --- a/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt +++ b/modules/dokkatoo-plugin/src/test/kotlin/dokka/parameters/builders/DokkaSourceSetBuilderTest.kt @@ -3,10 +3,7 @@ package dev.adamko.dokkatoo.dokka.parameters.builders import dev.adamko.dokkatoo.DokkatooExtension import dev.adamko.dokkatoo.DokkatooPlugin import dev.adamko.dokkatoo.dokka.parameters.DokkaSourceSetSpec -import dev.adamko.dokkatoo.utils.all_ -import dev.adamko.dokkatoo.utils.create_ -import dev.adamko.dokkatoo.utils.shouldContainAll -import dev.adamko.dokkatoo.utils.sourceLink_ +import dev.adamko.dokkatoo.utils.* import io.kotest.assertions.throwables.shouldThrow import io.kotest.core.spec.style.FunSpec import io.kotest.engine.spec.tempdir @@ -74,6 +71,17 @@ class DokkaSourceSetBuilderTest : FunSpec({ } } } + + test("expect externalDocumentationLink() util function adds link") { + val sourceSetSpec = project.createDokkaSourceSetSpec("test4") + val linkSpec = + sourceSetSpec.externalDocumentationLink_(URI("https://github.com/adamko-dev/dokkatoo/")) { + enabled.set(false) + } + linkSpec.name shouldBe "https://github.com/adamko-dev/dokkatoo/" + linkSpec.url.get() shouldBe URI("https://github.com/adamko-dev/dokkatoo/") + linkSpec.enabled.get() shouldBe false + } } diff --git a/modules/dokkatoo-plugin/src/testFixtures/kotlin/samWithReceiverWorkarounds.kt b/modules/dokkatoo-plugin/src/testFixtures/kotlin/samWithReceiverWorkarounds.kt index eac67196..15a849ec 100644 --- a/modules/dokkatoo-plugin/src/testFixtures/kotlin/samWithReceiverWorkarounds.kt +++ b/modules/dokkatoo-plugin/src/testFixtures/kotlin/samWithReceiverWorkarounds.kt @@ -2,9 +2,11 @@ package dev.adamko.dokkatoo.utils +import dev.adamko.dokkatoo.dokka.parameters.DokkaExternalDocumentationLinkSpec import dev.adamko.dokkatoo.dokka.parameters.DokkaPackageOptionsSpec import dev.adamko.dokkatoo.dokka.parameters.DokkaSourceLinkSpec import dev.adamko.dokkatoo.dokka.parameters.DokkaSourceSetSpec +import java.net.URI import org.gradle.api.DomainObjectCollection import org.gradle.api.NamedDomainObjectContainer import org.gradle.api.NamedDomainObjectProvider @@ -77,3 +79,9 @@ fun DokkaSourceSetSpec.sourceLink_( fun DokkaSourceSetSpec.perPackageOption_( action: DokkaPackageOptionsSpec.() -> Unit ): Unit = perPackageOption(action) + + +fun DokkaSourceSetSpec.externalDocumentationLink_( + url: URI, + action: DokkaExternalDocumentationLinkSpec.() -> Unit = {}, +): DokkaExternalDocumentationLinkSpec = externalDocumentationLink(url) { action() } From e3ae7e372a41e8e6bf507697b2176f07cdd4f6f9 Mon Sep 17 00:00:00 2001 From: Adam <897017+aSemy@users.noreply.github.com> Date: Sat, 19 Aug 2023 10:48:33 +0200 Subject: [PATCH 2/2] start adding links to external docs --- .../src/main/kotlin/DokkatooBasePlugin.kt | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt b/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt index b0cd33c6..76a4964c 100644 --- a/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt +++ b/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt @@ -228,6 +228,32 @@ constructor( url("https://kotlinlang.org/api/latest/jvm/stdlib/") } + maybeCreate("kotlinxCoroutines") { + // TODO link to coroutines docs + url("https://kotlinlang.org/api/latest/jvm/stdlib/") + } + + maybeCreate("kotlinxDateTime") { + // TODO check if this is the right link to kotlinx-datetime docs + url("https://kotlinlang.org/api/kotlinx-datetime/") + } + + maybeCreate("ktor") { + // TODO link to Ktor docs + url("https://kotlinlang.org/api/latest/jvm/stdlib/") + } + + maybeCreate("gradle") { + // TODO link to Gradle docs + url("https://kotlinlang.org/api/latest/jvm/stdlib/") + } + + // TODO get more links to existing docs + // - Kotlinx Serialization + + // TODO only add these links if source-set has a dependency that indicates the library is present + // (e.g. if kotlinx-serialization-core is present, then enable kxs link) + maybeCreate("androidSdk") { enabled.convention(this@dss.enableAndroidDocumentationLink) url("https://developer.android.com/reference/kotlin/")