diff --git a/dokka-runners/gradle-plugin/build.gradle.kts b/dokka-runners/gradle-plugin/build.gradle.kts deleted file mode 100644 index c518725c15..0000000000 --- a/dokka-runners/gradle-plugin/build.gradle.kts +++ /dev/null @@ -1,159 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("UnstableApiUsage") // jvm test suites & test report aggregation are incubating - -import buildsrc.utils.skipTestFixturesPublications - -plugins { - buildsrc.conventions.`kotlin-gradle-plugin` - kotlin("plugin.serialization") - - `java-test-fixtures` - `jvm-test-suite` - `test-report-aggregation` -} - -description = "Generates documentation for Kotlin projects (using Dokka)" - -dependencies { - // ideally there should be a 'dokka-core-api' dependency (that is very thin and doesn't drag in loads of unnecessary code) - // that would be used as an implementation dependency, while dokka-core would be used as a compileOnly dependency - // https://github.com/Kotlin/dokka/issues/2933 - implementation(libs.dokka.core) - - compileOnly(libs.gradlePlugin.kotlin) - compileOnly(libs.gradlePlugin.kotlin.klibCommonizerApi) - compileOnly(libs.gradlePlugin.android.dokkatoo) - compileOnly(libs.gradlePlugin.androidApi.dokkatoo) - - implementation(platform(libs.kotlinx.serialization.bom)) - implementation(libs.kotlinx.serialization.json) - - testFixturesImplementation(gradleApi()) - testFixturesImplementation(gradleTestKit()) - - testFixturesCompileOnly(libs.dokka.core) - testFixturesImplementation(platform(libs.kotlinx.serialization.bom)) - testFixturesImplementation(libs.kotlinx.serialization.json) - - testFixturesCompileOnly(libs.dokka.core) - - testFixturesApi(platform(libs.kotest.bom)) - testFixturesApi(libs.kotest.junit5Runner) - testFixturesApi(libs.kotest.assertionsCore) - testFixturesApi(libs.kotest.assertionsJson) - testFixturesApi(libs.kotest.datatest) - - // don't define test dependencies here, instead define them in the testing.suites {} configuration below -} - -// TODO [structure-refactoring] change / extract? -gradlePlugin { - isAutomatedPublishing = true - - plugins.register("dokkatoo") { - id = "org.jetbrains.dokka.dokkatoo" - displayName = "Dokkatoo" - description = "Generates documentation for Kotlin projects (using Dokka)" - implementationClass = "org.jetbrains.dokka.dokkatoo.DokkatooPlugin" - } - - fun registerDokkaPlugin( - pluginClass: String, - shortName: String, - longName: String = shortName, - ) { - plugins.register(pluginClass) { - id = "org.jetbrains.dokka.dokkatoo-${shortName.toLowerCase()}" - displayName = "Dokkatoo $shortName" - description = "Generates $longName documentation for Kotlin projects (using Dokka)" - implementationClass = "org.jetbrains.dokka.dokkatoo.formats.$pluginClass" - } - } - registerDokkaPlugin("DokkatooGfmPlugin", "GFM", longName = "GFM (GitHub Flavoured Markdown)") - registerDokkaPlugin("DokkatooHtmlPlugin", "HTML") - registerDokkaPlugin("DokkatooJavadocPlugin", "Javadoc") - registerDokkaPlugin("DokkatooJekyllPlugin", "Jekyll") - - plugins.configureEach { - website.set("https://github.com/adamko-dev/dokkatoo/") - vcsUrl.set("https://github.com/adamko-dev/dokkatoo.git") - tags.addAll( - "dokka", - "dokkatoo", - "kotlin", - "kdoc", - "android", - "documentation", - "javadoc", - "html", - "markdown", - "gfm", - "website", - ) - } -} - -kotlin { - target { - compilations.configureEach { - // TODO Dokkatoo uses Gradle 8, while Dokka uses Gradle 7, which has an older version of Kotlin that - // doesn't include these options - so update them or update Gradle. -// compilerOptions.configure { -// freeCompilerArgs.addAll( -// "-opt-in=org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi", -// ) -// } - } - } -} - -skipTestFixturesPublications() - -val dokkatooVersion = provider { project.version.toString() } - -val dokkatooConstantsProperties = objects.mapProperty().apply { - put("DOKKATOO_VERSION", dokkatooVersion) - put("DOKKA_VERSION", libs.versions.gradlePlugin.dokka) -} - -val buildConfigFileContents: Provider = - dokkatooConstantsProperties.map { constants -> - - val vals = constants.entries - .sortedBy { it.key } - .joinToString("\n") { (k, v) -> - """const val $k = "$v"""" - }.prependIndent(" ") - - resources.text.fromString( - """ - |package org.jetbrains.dokka.dokkatoo.internal - | - |@DokkatooInternalApi - |object DokkatooConstants { - |$vals - |} - | - """.trimMargin() - ) - } - -val generateDokkatooConstants by tasks.registering(Sync::class) { - group = project.name - - val buildConfigFileContents = buildConfigFileContents - - from(buildConfigFileContents) { - rename { "DokkatooConstants.kt" } - into("dev/adamko/dokkatoo/internal/") - } - - into(layout.buildDirectory.dir("generated-source/main/kotlin/")) -} - -kotlin.sourceSets.main { - kotlin.srcDir(generateDokkatooConstants.map { it.destinationDir }) -} diff --git a/dokka-runners/gradle-plugin/buildSrc/build.gradle.kts b/dokka-runners/gradle-plugin/buildSrc/build.gradle.kts deleted file mode 100644 index a4b23ac5a5..0000000000 --- a/dokka-runners/gradle-plugin/buildSrc/build.gradle.kts +++ /dev/null @@ -1,20 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -import org.gradle.kotlin.dsl.support.expectedKotlinDslPluginsVersion - -plugins { - `kotlin-dsl` -} - -dependencies { - implementation("org.gradle.kotlin:gradle-kotlin-dsl-plugins:$expectedKotlinDslPluginsVersion") - implementation("org.jetbrains.kotlin:kotlin-serialization:$embeddedKotlinVersion") -} - -java { - toolchain { - languageVersion.set(JavaLanguageVersion.of(11)) - } -} diff --git a/dokka-runners/gradle-plugin/buildSrc/settings.gradle.kts b/dokka-runners/gradle-plugin/buildSrc/settings.gradle.kts deleted file mode 100644 index e033fb43fa..0000000000 --- a/dokka-runners/gradle-plugin/buildSrc/settings.gradle.kts +++ /dev/null @@ -1,25 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -rootProject.name = "buildSrc" - -pluginManagement { - repositories { - mavenCentral() - gradlePluginPortal() - google() - } -} - -@Suppress("UnstableApiUsage") -dependencyResolutionManagement { - - repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) - - repositories { - mavenCentral() - gradlePluginPortal() - google() - } -} diff --git a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts b/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts deleted file mode 100644 index dc9e088823..0000000000 --- a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts +++ /dev/null @@ -1,28 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package buildsrc.conventions - -/** - * A convention plugin that sets up common config and sensible defaults for all subprojects. - */ - -plugins { - base -} - -if (project != rootProject) { - project.version = rootProject.version - project.group = rootProject.group -} - -tasks.withType().configureEach { - // https://docs.gradle.org/current/userguide/working_with_files.html#sec:reproducible_archives - isPreserveFileTimestamps = false - isReproducibleFileOrder = true -} - -tasks.withType().configureEach { - includeEmptyDirs = false -} diff --git a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts b/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts deleted file mode 100644 index b11812b1d4..0000000000 --- a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/java-base.gradle.kts +++ /dev/null @@ -1,17 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package buildsrc.conventions - -plugins { - id("buildsrc.conventions.base") - `java` -} - -extensions.getByType().apply { - toolchain { - languageVersion.set(JavaLanguageVersion.of(11)) - } - withSourcesJar() -} diff --git a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts b/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts deleted file mode 100644 index 32b3b73d69..0000000000 --- a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/conventions/kotlin-gradle-plugin.gradle.kts +++ /dev/null @@ -1,36 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package buildsrc.conventions - -plugins { - id("buildsrc.conventions.base") - id("buildsrc.conventions.java-base") - id("org.gradle.kotlin.kotlin-dsl") -} - -val createJavadocJarReadme by tasks.registering(Sync::class) { - description = "generate a readme.txt for the Javadoc JAR" - from( - resources.text.fromString( - """ - This Javadoc JAR is intentionally empty. - - For documentation, see the sources JAR or https://github.com/adamko-dev/dokkatoo/ - - """.trimIndent() - ) - ) { - rename { "readme.txt" } - } - into(temporaryDir) -} - - -// The Gradle Publish Plugin enables the Javadoc JAR in afterEvaluate, so find it lazily -tasks.withType() - .matching { it.name == "javadocJar" } - .configureEach { - from(createJavadocJarReadme) - } diff --git a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt b/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt deleted file mode 100644 index d66da929f2..0000000000 --- a/dokka-runners/gradle-plugin/buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt +++ /dev/null @@ -1,20 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package buildsrc.utils - -import org.gradle.api.Project -import org.gradle.api.component.AdhocComponentWithVariants -import org.gradle.kotlin.dsl.get - -/** - * Don't publish test fixtures (which causes warnings when publishing) - * - * https://docs.gradle.org/current/userguide/java_testing.html#publishing_test_fixtures - */ -fun Project.skipTestFixturesPublications() { - val javaComponent = components["java"] as AdhocComponentWithVariants - javaComponent.withVariantsFromConfiguration(configurations["testFixturesApiElements"]) { skip() } - javaComponent.withVariantsFromConfiguration(configurations["testFixturesRuntimeElements"]) { skip() } -} diff --git a/dokka-runners/gradle-plugin/settings.gradle.kts b/dokka-runners/gradle-plugin/settings.gradle.kts deleted file mode 100644 index d5d2d7b5ed..0000000000 --- a/dokka-runners/gradle-plugin/settings.gradle.kts +++ /dev/null @@ -1,32 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("UnstableApiUsage") - -rootProject.name = "gradle-plugin" - -pluginManagement { - repositories { - mavenCentral() - gradlePluginPortal() - google() - } -} - -dependencyResolutionManagement { - repositories { - mavenCentral() - gradlePluginPortal() - google() - } - - versionCatalogs { - create("libs") { - from(files("../../gradle/libs.versions.toml")) - } - } -} - -enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") -enableFeaturePreview("STABLE_CONFIGURATION_CACHE") diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooBasePlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooBasePlugin.kt deleted file mode 100644 index 37bffd4c2f..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooBasePlugin.kt +++ /dev/null @@ -1,359 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo - -import kotlinx.serialization.ExperimentalSerializationApi -import kotlinx.serialization.json.Json -import org.gradle.api.NamedDomainObjectContainer -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.artifacts.Configuration -import org.gradle.api.file.ProjectLayout -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.model.ObjectFactory -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.provider.ProviderFactory -import org.gradle.api.tasks.TaskContainer -import org.gradle.kotlin.dsl.* -import org.gradle.language.base.plugins.LifecycleBasePlugin -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKATOO_BASE_ATTRIBUTE -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKATOO_CATEGORY_ATTRIBUTE -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKA_FORMAT_ATTRIBUTE -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec -import org.jetbrains.dokka.dokkatoo.dokka.parameters.KotlinPlatform -import org.jetbrains.dokka.dokkatoo.dokka.parameters.VisibilityModifier -import org.jetbrains.dokka.dokkatoo.internal.* -import org.jetbrains.dokka.dokkatoo.tasks.DokkatooGenerateTask -import org.jetbrains.dokka.dokkatoo.tasks.DokkatooPrepareModuleDescriptorTask -import org.jetbrains.dokka.dokkatoo.tasks.DokkatooTask -import java.io.File -import javax.inject.Inject - -/** - * The base plugin for Dokkatoo. Sets up Dokkatoo and configures default values, but does not - * add any specific config (specifically, it does not create Dokka Publications). - */ -abstract class DokkatooBasePlugin -@DokkatooInternalApi -@Inject -constructor( - private val providers: ProviderFactory, - private val layout: ProjectLayout, - private val objects: ObjectFactory, -) : Plugin { - - override fun apply(target: Project) { - // apply the lifecycle-base plugin so the clean task is available - target.pluginManager.apply(LifecycleBasePlugin::class) - - val dokkatooExtension = createExtension(target) - - target.tasks.createDokkaLifecycleTasks() - - val configurationAttributes = objects.newInstance() - - target.dependencies.attributesSchema { - attribute(DOKKATOO_BASE_ATTRIBUTE) - attribute(DOKKATOO_CATEGORY_ATTRIBUTE) - attribute(DOKKA_FORMAT_ATTRIBUTE) - } - - target.configurations.register(dependencyContainerNames.dokkatoo) { - description = "Fetch all Dokkatoo files from all configurations in other subprojects" - asConsumer() - isVisible = false - attributes { - attribute(DOKKATOO_BASE_ATTRIBUTE, configurationAttributes.dokkatooBaseUsage) - } - } - - configureDokkaPublicationsDefaults(dokkatooExtension) - dokkatooExtension.dokkatooSourceSets.configureDefaults( - sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault - ) - - target.tasks.withType().configureEach { - cacheDirectory.convention(dokkatooExtension.dokkatooCacheDirectory) - workerDebugEnabled.convention(false) - workerLogFile.convention(temporaryDir.resolve("dokka-worker.log")) - workerJvmArgs.set( - listOf( - //"-XX:MaxMetaspaceSize=512m", - "-XX:+HeapDumpOnOutOfMemoryError", - "-XX:+AlwaysPreTouch", // https://github.com/gradle/gradle/issues/3093#issuecomment-387259298 - //"-XX:StartFlightRecording=disk=true,name={path.drop(1).map { if (it.isLetterOrDigit()) it else '-' }.joinToString("")},dumponexit=true,duration=30s", - //"-XX:FlightRecorderOptions=repository=$baseDir/jfr,stackdepth=512", - ) - ) - dokkaConfigurationJsonFile.convention(temporaryDir.resolve("dokka-configuration.json")) - } - - target.tasks.withType().configureEach { - moduleName.convention(dokkatooExtension.moduleName) - includes.from(providers.provider { dokkatooExtension.dokkatooSourceSets.flatMap { it.includes } }) - modulePath.convention(dokkatooExtension.modulePath) - } - - target.tasks.withType().configureEach { - - publicationEnabled.convention(true) - onlyIf("publication must be enabled") { publicationEnabled.getOrElse(true) } - - generator.dokkaSourceSets.addAllLater( - providers.provider { - // exclude suppressed source sets as early as possible, to avoid unnecessary dependency resolution - dokkatooExtension.dokkatooSourceSets.filterNot { it.suppress.get() } - } - ) - - generator.dokkaSourceSets.configureDefaults( - sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault - ) - } - - dokkatooExtension.dokkatooSourceSets.configureDefaults( - sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault - ) - } - - private fun createExtension(project: Project): DokkatooExtension { - val dokkatooExtension = project.extensions.create(EXTENSION_NAME).apply { - moduleName.convention(providers.provider { project.name }) - moduleVersion.convention(providers.provider { project.version.toString() }) - modulePath.convention(project.pathAsFilePath()) - konanHome.convention( - providers - .provider { - // konanHome is set into in extraProperties: - // https://github.com/JetBrains/kotlin/blob/v1.9.0/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/native/KotlinNativeTargetPreset.kt#L35-L38 - project.extensions.extraProperties.get("konanHome") as? String? - } - .map { File(it) } - ) - - sourceSetScopeDefault.convention(project.path) - dokkatooPublicationDirectory.convention(layout.buildDirectory.dir("dokka")) - dokkatooModuleDirectory.convention(layout.buildDirectory.dir("dokka-module")) - dokkatooConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config")) - } - - dokkatooExtension.versions { - jetbrainsDokka.convention(DokkatooConstants.DOKKA_VERSION) - jetbrainsMarkdown.convention("0.3.1") - freemarker.convention("2.3.31") - kotlinxHtml.convention("0.8.0") - kotlinxCoroutines.convention("1.6.4") - } - - return dokkatooExtension - } - - /** Set defaults in all [DokkatooExtension.dokkatooPublications]s */ - private fun configureDokkaPublicationsDefaults( - dokkatooExtension: DokkatooExtension, - ) { - dokkatooExtension.dokkatooPublications.all { - enabled.convention(true) - cacheRoot.convention(dokkatooExtension.dokkatooCacheDirectory) - delayTemplateSubstitution.convention(false) - failOnWarning.convention(false) - finalizeCoroutines.convention(false) - moduleName.convention(dokkatooExtension.moduleName) - moduleVersion.convention(dokkatooExtension.moduleVersion) - offlineMode.convention(false) - outputDir.convention(dokkatooExtension.dokkatooPublicationDirectory) - suppressInheritedMembers.convention(false) - suppressObviousFunctions.convention(true) - } - } - - /** Set conventions for all [DokkaSourceSetSpec] properties */ - private fun NamedDomainObjectContainer.configureDefaults( - sourceSetScopeConvention: Property, - ) { - configureEach dss@{ - analysisPlatform.convention(KotlinPlatform.DEFAULT) - displayName.convention( - analysisPlatform.map { platform -> - // Match existing Dokka naming conventions. (This should probably be simplified!) - when { - // Multiplatform source sets (e.g. commonMain, jvmMain, macosMain) - name.endsWith("Main") -> name.substringBeforeLast("Main") - - // indeterminate source sets should be named by the Kotlin platform - else -> platform.displayName - } - } - ) - documentedVisibilities.convention(setOf(VisibilityModifier.PUBLIC)) - jdkVersion.convention(8) - - enableKotlinStdLibDocumentationLink.convention(true) - enableJdkDocumentationLink.convention(true) - enableAndroidDocumentationLink.convention( - analysisPlatform.map { it == KotlinPlatform.AndroidJVM } - ) - - reportUndocumented.convention(false) - skipDeprecated.convention(false) - skipEmptyPackages.convention(true) - sourceSetScope.convention(sourceSetScopeConvention) - - // Manually added sourceSets should not be suppressed by default. dokkatooSourceSets that are - // automatically added by DokkatooKotlinAdapter will have a sensible value for suppress. - suppress.convention(false) - - suppressGeneratedFiles.convention(true) - - sourceLinks.configureEach { - localDirectory.convention(layout.projectDirectory) - remoteLineSuffix.convention("#L") - } - - perPackageOptions.configureEach { - matchingRegex.convention(".*") - suppress.convention(false) - skipDeprecated.convention(false) - reportUndocumented.convention(false) - } - - externalDocumentationLinks { - configureEach { - enabled.convention(true) - packageListUrl.convention(url.map { it.appendPath("package-list") }) - } - - maybeCreate("jdk") { - enabled.convention(this@dss.enableJdkDocumentationLink) - url(this@dss.jdkVersion.map { jdkVersion -> - when { - jdkVersion < 11 -> "https://docs.oracle.com/javase/${jdkVersion}/docs/api/" - else -> "https://docs.oracle.com/en/java/javase/${jdkVersion}/docs/api/" - } - }) - packageListUrl(this@dss.jdkVersion.map { jdkVersion -> - when { - jdkVersion < 11 -> "https://docs.oracle.com/javase/${jdkVersion}/docs/api/package-list" - else -> "https://docs.oracle.com/en/java/javase/${jdkVersion}/docs/api/element-list" - } - }) - } - - maybeCreate("kotlinStdlib") { - enabled.convention(this@dss.enableKotlinStdLibDocumentationLink) - url("https://kotlinlang.org/api/latest/jvm/stdlib/") - } - - maybeCreate("androidSdk") { - enabled.convention(this@dss.enableAndroidDocumentationLink) - url("https://developer.android.com/reference/kotlin/") - } - - maybeCreate("androidX") { - enabled.convention(this@dss.enableAndroidDocumentationLink) - url("https://developer.android.com/reference/kotlin/") - packageListUrl("https://developer.android.com/reference/kotlin/androidx/package-list") - } - } - } - } - - private fun TaskContainer.createDokkaLifecycleTasks() { - register(taskNames.generate) { - description = "Generates Dokkatoo publications for all formats" - dependsOn(withType()) - } - } - - // workaround for https://github.com/gradle/gradle/issues/23708 - private fun RegularFileProperty.convention(file: File): RegularFileProperty = - convention(objects.fileProperty().fileValue(file)) - - // workaround for https://github.com/gradle/gradle/issues/23708 - private fun RegularFileProperty.convention(file: Provider): RegularFileProperty = - convention(objects.fileProperty().fileProvider(file)) - - companion object { - - const val EXTENSION_NAME = "dokkatoo" - - /** - * The group of all Dokkatoo [Gradle tasks][org.gradle.api.Task]. - * - * @see org.gradle.api.Task.getGroup - */ - const val TASK_GROUP = "dokkatoo" - - /** The names of [Gradle tasks][org.gradle.api.Task] created by Dokkatoo */ - val taskNames = TaskNames(null) - - /** The names of [Configuration]s created by Dokkatoo */ - val dependencyContainerNames = DependencyContainerNames(null) - - internal val jsonMapper = Json { - prettyPrint = true - @OptIn(ExperimentalSerializationApi::class) - prettyPrintIndent = " " - } - } - - @DokkatooInternalApi - abstract class HasFormatName { - abstract val formatName: String? - - /** Appends [formatName] to the end of the string, camelcase style, if [formatName] is not null */ - protected fun String.appendFormat(): String = - when (val name = formatName) { - null -> this - else -> this + name.uppercaseFirstChar() - } - } - - /** - * Names of the Gradle [Configuration]s used by the [Dokkatoo Plugin][DokkatooBasePlugin]. - * - * Beware the confusing terminology: - * - [Gradle Configurations][org.gradle.api.artifacts.Configuration] - share files between subprojects. Each has a name. - * - [DokkaConfiguration][org.jetbrains.dokka.DokkaConfiguration] - parameters for executing the Dokka Generator - */ - @DokkatooInternalApi - class DependencyContainerNames(override val formatName: String?) : HasFormatName() { - - val dokkatoo = "dokkatoo".appendFormat() - - /** Name of the [Configuration] that _consumes_ all [org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription] files */ - val dokkatooModuleFilesConsumer = "dokkatooModule".appendFormat() - - /** Name of the [Configuration] that _provides_ all [org.jetbrains.dokka.DokkaConfiguration.DokkaModuleDescription] files to other projects */ - val dokkatooModuleFilesProvider = "dokkatooModuleElements".appendFormat() - - /** - * Classpath used to execute the Dokka Generator. - * - * Extends [dokkaPluginsClasspath], so Dokka plugins and their dependencies are included. - */ - val dokkaGeneratorClasspath = "dokkatooGeneratorClasspath".appendFormat() - - /** Dokka Plugins (including transitive dependencies, so this can be passed to the Dokka Generator Worker classpath) */ - val dokkaPluginsClasspath = "dokkatooPlugin".appendFormat() - - /** - * Dokka Plugins (excluding transitive dependencies) will be used to create Dokka Generator Parameters - * - * Generally, this configuration should not be invoked manually. Instead, use [dokkaPluginsClasspath]. - */ - val dokkaPluginsIntransitiveClasspath = "dokkatooPluginIntransitive".appendFormat() - } - - @DokkatooInternalApi - class TaskNames(override val formatName: String?) : HasFormatName() { - val generate = "dokkatooGenerate".appendFormat() - val generatePublication = "dokkatooGeneratePublication".appendFormat() - val generateModule = "dokkatooGenerateModule".appendFormat() - val prepareModuleDescriptor = "prepareDokkatooModuleDescriptor".appendFormat() - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooExtension.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooExtension.kt deleted file mode 100644 index 099b31ab1c..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooExtension.kt +++ /dev/null @@ -1,134 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo - -import org.gradle.api.NamedDomainObjectContainer -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.model.ObjectFactory -import org.gradle.api.plugins.ExtensionAware -import org.gradle.api.provider.Property -import org.gradle.kotlin.dsl.newInstance -import org.jetbrains.dokka.dokkatoo.dokka.DokkaPublication -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec -import org.jetbrains.dokka.dokkatoo.internal.* -import java.io.Serializable - -/** - * Configure the behaviour of the [DokkatooBasePlugin]. - */ -abstract class DokkatooExtension -@DokkatooInternalApi -constructor( - objects: ObjectFactory, -) : ExtensionAware, Serializable { - - /** Directory into which [DokkaPublication]s will be produced */ - abstract val dokkatooPublicationDirectory: DirectoryProperty - - /** Directory into which Dokka Modules will be produced */ - abstract val dokkatooModuleDirectory: DirectoryProperty - - abstract val dokkatooConfigurationsDirectory: DirectoryProperty - - /** Default Dokkatoo cache directory */ - abstract val dokkatooCacheDirectory: DirectoryProperty - - abstract val moduleName: Property - abstract val moduleVersion: Property - abstract val modulePath: Property - - /** - * An arbitrary string used to group source sets that originate from different Gradle subprojects. - * - * This is primarily used by Kotlin Multiplatform projects, which can have multiple source sets - * per subproject. - * - * Defaults to [the path of the subproject][org.gradle.api.Project.getPath]. - */ - abstract val sourceSetScopeDefault: Property - - /** - * The Konan home directory, which contains libraries for Kotlin/Native development. - * - * This is only required as a workaround to fetch the compile-time dependencies in Kotlin/Native - * projects with a version below 2.0. - */ - // This property should be removed when Dokkatoo only supports KGP 2 or higher. - @DokkatooInternalApi - abstract val konanHome: RegularFileProperty - - /** - * Configuration for creating Dokka Publications. - * - * Each publication will generate one Dokka site based on the included Dokka Source Sets. - * - * The type of site is determined by the Dokka Plugins. By default, an HTML site will be generated. - */ - val dokkatooPublications: NamedDomainObjectContainer = - extensions.adding( - "dokkatooPublications", - objects.domainObjectContainer { named -> objects.newInstance(named, pluginsConfiguration) } - ) - - /** - * Dokka Source Sets describe the source code that should be included in a Dokka Publication. - * - * Dokka will not generate documentation unless there is at least there is at least one Dokka Source Set. - * - * TODO make sure dokkatooSourceSets doc is up to date... - * - * Only source sets that are contained within _this project_ should be included here. - * To merge source sets from other projects, use the Gradle dependencies block. - * - * ```kotlin - * dependencies { - * // merge :other-project into this project's Dokka Configuration - * dokka(project(":other-project")) - * } - * ``` - * - * Or, to include other Dokka Publications as a Dokka Module use - * - * ```kotlin - * dependencies { - * // include :other-project as a module in this project's Dokka Configuration - * dokkaModule(project(":other-project")) - * } - * ``` - * - * Dokka will merge Dokka Source Sets from other subprojects if... - */ - val dokkatooSourceSets: NamedDomainObjectContainer = - extensions.adding("dokkatooSourceSets", objects.domainObjectContainer()) - - /** - * Dokka Plugin are used to configure the way Dokka generates a format. - * Some plugins can be configured via parameters, and those parameters are stored in this - * container. - */ - val pluginsConfiguration: DokkaPluginParametersContainer = - extensions.adding("pluginsConfiguration", objects.dokkaPluginParametersContainer()) - - /** - * Versions of dependencies that Dokkatoo will use to run Dokka Generator. - * - * These versions can be set to change the versions of dependencies that Dokkatoo uses defaults, - * or can be read to align versions. - */ - val versions: Versions = extensions.adding("versions", objects.newInstance()) - - interface Versions : ExtensionAware { - - /** Default version used for Dokka dependencies */ - val jetbrainsDokka: Property - val jetbrainsMarkdown: Property - val freemarker: Property - val kotlinxHtml: Property - val kotlinxCoroutines: Property - - companion object - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooPlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooPlugin.kt deleted file mode 100644 index 88638e4664..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/DokkatooPlugin.kt +++ /dev/null @@ -1,36 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo - -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.kotlin.dsl.apply -import org.jetbrains.dokka.dokkatoo.formats.DokkatooGfmPlugin -import org.jetbrains.dokka.dokkatoo.formats.DokkatooHtmlPlugin -import org.jetbrains.dokka.dokkatoo.formats.DokkatooJavadocPlugin -import org.jetbrains.dokka.dokkatoo.formats.DokkatooJekyllPlugin -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi - -/** - * Dokkatoo Gradle Plugin. - * - * Creates all necessary defaults to generate documentation for HTML, Jekyll, Markdown, and Javadoc formats. - */ -abstract class DokkatooPlugin -@DokkatooInternalApi -constructor() : Plugin { - - override fun apply(target: Project) { - with(target.pluginManager) { - apply(type = DokkatooBasePlugin::class) - - // auto-apply the custom format plugins - apply(type = DokkatooGfmPlugin::class) - apply(type = DokkatooHtmlPlugin::class) - apply(type = DokkatooJavadocPlugin::class) - apply(type = DokkatooJekyllPlugin::class) - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooAndroidAdapter.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooAndroidAdapter.kt deleted file mode 100644 index faf45263be..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooAndroidAdapter.kt +++ /dev/null @@ -1,218 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.adapters - -import com.android.build.api.dsl.CommonExtension -import com.android.build.gradle.AppExtension -import com.android.build.gradle.BaseExtension -import com.android.build.gradle.LibraryExtension -import com.android.build.gradle.TestExtension -import com.android.build.gradle.api.BaseVariant -import com.android.build.gradle.internal.dependency.VariantDependencies -import com.android.build.gradle.internal.publishing.AndroidArtifacts.ArtifactType.CLASSES_JAR -import com.android.build.gradle.internal.publishing.AndroidArtifacts.ArtifactType.PROCESSED_JAR -import org.gradle.api.DomainObjectSet -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.artifacts.ConfigurationContainer -import org.gradle.api.artifacts.type.ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE -import org.gradle.api.file.FileCollection -import org.gradle.api.logging.Logging -import org.gradle.api.model.ObjectFactory -import org.gradle.api.provider.ProviderFactory -import org.gradle.kotlin.dsl.* -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin -import org.jetbrains.dokka.dokkatoo.DokkatooExtension -import org.jetbrains.dokka.dokkatoo.dokka.parameters.KotlinPlatform -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.collectIncomingFiles -import javax.inject.Inject - -@DokkatooInternalApi -abstract class DokkatooAndroidAdapter @Inject constructor( - private val objects: ObjectFactory, -) : Plugin { - - override fun apply(project: Project) { - logger.info("applied DokkatooAndroidAdapter to ${project.path}") - - project.plugins.withType().configureEach { - project.pluginManager.apply { - withPlugin("com.android.base") { configure(project) } - withPlugin("com.android.application") { configure(project) } - withPlugin("com.android.library") { configure(project) } - } - } - } - - protected fun configure(project: Project) { - val dokkatooExtension = project.extensions.getByType() - - val androidExt = AndroidExtensionWrapper(project) - - if (androidExt == null) { - logger.warn("DokkatooAndroidAdapter could not get Android Extension for project ${project.path}") - return - } - - dokkatooExtension.dokkatooSourceSets.configureEach { - - classpath.from( - analysisPlatform.map { analysisPlatform -> - when (analysisPlatform) { - KotlinPlatform.AndroidJVM -> - AndroidClasspathCollector( - androidExt = androidExt, - configurations = project.configurations, - objects = objects, - ) - - else -> - objects.fileCollection() - } - } - ) - } - } - - @DokkatooInternalApi - companion object { - private val logger = Logging.getLogger(DokkatooAndroidAdapter::class.java) - } -} - -private fun AndroidExtensionWrapper( - project: Project -): AndroidExtensionWrapper? { - -// fetching _all_ configuration names is very brute force and should probably be refined to -// only fetch those that match a specific DokkaSourceSetSpec - - return runCatching { - val androidExt = project.extensions.getByType() - AndroidExtensionWrapper.forBaseExtension( - androidExt = androidExt, - providers = project.providers, - objects = project.objects - ) - }.recoverCatching { - val androidExt = project.extensions.getByType(CommonExtension::class) - AndroidExtensionWrapper.forCommonExtension(androidExt) - }.getOrNull() -} - -/** - * Android Gradle Plugin is having a refactor. Try to wrap the Android extension so that Dokkatoo - * can still access the configuration names without caring about which AGP version is in use. - */ -private interface AndroidExtensionWrapper { - fun variantConfigurationNames(): Set - - companion object { - - @Suppress("DEPRECATION") - fun forBaseExtension( - androidExt: BaseExtension, - providers: ProviderFactory, - objects: ObjectFactory, - ): AndroidExtensionWrapper { - return object : AndroidExtensionWrapper { - /** Fetch all configuration names used by all variants. */ - override fun variantConfigurationNames(): Set { - val collector = objects.domainObjectSet(BaseVariant::class) - - val variants: DomainObjectSet = - collector.apply { - addAllLater(providers.provider { - when (androidExt) { - is LibraryExtension -> androidExt.libraryVariants - is AppExtension -> androidExt.applicationVariants - is TestExtension -> androidExt.applicationVariants - else -> emptyList() - } - }) - } - - return buildSet { - variants.forEach { - add(it.compileConfiguration.name) - add(it.runtimeConfiguration.name) - add(it.annotationProcessorConfiguration.name) - } - } - } - } - } - - fun forCommonExtension( - androidExt: CommonExtension<*, *, *, *> - ): AndroidExtensionWrapper { - return object : AndroidExtensionWrapper { - /** Fetch all configuration names used by all variants. */ - override fun variantConfigurationNames(): Set { - return buildSet { - @Suppress("UnstableApiUsage") - androidExt.sourceSets.forEach { - add(it.apiConfigurationName) - add(it.compileOnlyConfigurationName) - add(it.implementationConfigurationName) - add(it.runtimeOnlyConfigurationName) - add(it.wearAppConfigurationName) - add(it.annotationProcessorConfigurationName) - } - } - } - } - } - } -} - - -/** - * A utility for determining the classpath of an Android compilation. - * - * It's important that this class is separate from [DokkatooAndroidAdapter]. It must be separate - * because it uses Android Gradle Plugin classes (like [BaseExtension]). Were it not separate, and - * these classes were present in the function signatures of [DokkatooAndroidAdapter], then when - * Gradle tries to create a decorated instance of [DokkatooAndroidAdapter] it will if the project - * does not have the Android Gradle Plugin applied, because the classes will be missing. - */ -private object AndroidClasspathCollector { - - operator fun invoke( - androidExt: AndroidExtensionWrapper, - configurations: ConfigurationContainer, - objects: ObjectFactory, - ): FileCollection { - val compilationClasspath = objects.fileCollection() - - fun collectConfiguration(named: String) { - listOf( - // need to fetch multiple different types of files, because AGP is weird and doesn't seem - // to have a 'just give me normal JVM classes' option - ARTIFACT_TYPE_ATTRIBUTE to PROCESSED_JAR.type, - ARTIFACT_TYPE_ATTRIBUTE to CLASSES_JAR.type, - ).forEach { (attribute, attributeValue) -> - configurations.collectIncomingFiles(named, collector = compilationClasspath) { - attributes { - attribute(attribute, attributeValue) - } - lenient(true) - } - } - } - - // fetch android.jar - collectConfiguration(named = VariantDependencies.CONFIG_NAME_ANDROID_APIS) - - val variantConfigurations = androidExt.variantConfigurationNames() - - for (variantConfig in variantConfigurations) { - collectConfiguration(named = variantConfig) - } - - return compilationClasspath - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooJavaAdapter.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooJavaAdapter.kt deleted file mode 100644 index 9758ed8eee..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooJavaAdapter.kt +++ /dev/null @@ -1,45 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.adapters - -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.logging.Logging -import org.gradle.api.plugins.JavaBasePlugin -import org.gradle.api.plugins.JavaPluginExtension -import org.gradle.kotlin.dsl.getByType -import org.gradle.kotlin.dsl.withType -import org.jetbrains.dokka.dokkatoo.DokkatooExtension -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import javax.inject.Inject - -/** - * Apply Java specific configuration to the Dokkatoo plugin. - * - * **Must be applied *after* [org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin]** - */ -@DokkatooInternalApi -abstract class DokkatooJavaAdapter @Inject constructor() : Plugin { - - private val logger = Logging.getLogger(this::class.java) - - override fun apply(project: Project) { - logger.info("applied DokkatooJavaAdapter to ${project.path}") - - // wait for the Java plugin to be applied - project.plugins.withType().configureEach { - - // fetch the toolchain, and use the language version as Dokka's jdkVersion - val toolchainLanguageVersion = project.extensions.getByType() - .toolchain - .languageVersion - - val dokka = project.extensions.getByType() - dokka.dokkatooSourceSets.configureEach { - jdkVersion.set(toolchainLanguageVersion.map { it.asInt() }.orElse(8)) - } - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooKotlinAdapter.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooKotlinAdapter.kt deleted file mode 100644 index 8f39cc762d..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/adapters/DokkatooKotlinAdapter.kt +++ /dev/null @@ -1,465 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.adapters - -import com.android.build.gradle.api.ApplicationVariant -import com.android.build.gradle.api.LibraryVariant -import org.gradle.api.Named -import org.gradle.api.NamedDomainObjectContainer -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.FileCollection -import org.gradle.api.logging.Logging -import org.gradle.api.model.ObjectFactory -import org.gradle.api.plugins.ExtensionContainer -import org.gradle.api.provider.ListProperty -import org.gradle.api.provider.Provider -import org.gradle.api.provider.ProviderFactory -import org.gradle.api.provider.SetProperty -import org.gradle.kotlin.dsl.* -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin -import org.jetbrains.dokka.dokkatoo.DokkatooExtension -import org.jetbrains.dokka.dokkatoo.adapters.DokkatooKotlinAdapter.Companion.currentKotlinToolingVersion -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetIdSpec -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetIdSpec.Companion.dokkaSourceSetIdSpec -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec -import org.jetbrains.dokka.dokkatoo.dokka.parameters.KotlinPlatform -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.not -import org.jetbrains.kotlin.commonizer.KonanDistribution -import org.jetbrains.kotlin.commonizer.platformLibsDir -import org.jetbrains.kotlin.commonizer.stdlib -import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension -import org.jetbrains.kotlin.gradle.dsl.KotlinProjectExtension -import org.jetbrains.kotlin.gradle.dsl.KotlinSingleTargetExtension -import org.jetbrains.kotlin.gradle.plugin.KotlinCompilation -import org.jetbrains.kotlin.gradle.plugin.KotlinCompilation.Companion.MAIN_COMPILATION_NAME -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet -import org.jetbrains.kotlin.gradle.plugin.getKotlinPluginVersion -import org.jetbrains.kotlin.gradle.plugin.mpp.AbstractKotlinNativeCompilation -import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinJvmAndroidCompilation -import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinMetadataCompilation -import org.jetbrains.kotlin.konan.target.KonanTarget -import org.jetbrains.kotlin.tooling.core.KotlinToolingVersion -import java.io.File -import javax.inject.Inject - -/** - * The [DokkatooKotlinAdapter] plugin will automatically register Kotlin source sets as Dokka source sets. - * - * This is not a standalone plugin, it requires [org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin] is also applied. - */ -@DokkatooInternalApi -abstract class DokkatooKotlinAdapter @Inject constructor( - private val objects: ObjectFactory, - private val providers: ProviderFactory, -) : Plugin { - - override fun apply(project: Project) { - logger.info("applied DokkatooKotlinAdapter to ${project.path}") - - project.plugins.withType().configureEach { - project.pluginManager.apply { - withPlugin("org.jetbrains.kotlin.android") { exec(project) } - withPlugin("org.jetbrains.kotlin.js") { exec(project) } - withPlugin("org.jetbrains.kotlin.jvm") { exec(project) } - withPlugin("org.jetbrains.kotlin.multiplatform") { exec(project) } - } - } - } - - private fun exec(project: Project) { - val kotlinExtension = project.extensions.findKotlinExtension() ?: run { - logger.info("could not find Kotlin Extension") - return - } - logger.info("Configuring Dokkatoo in Gradle Kotlin Project ${project.path}") - - val dokkatooExtension = project.extensions.getByType() - - // first fetch the relevant properties of all KotlinCompilations - val compilationDetailsBuilder = KotlinCompilationDetailsBuilder( - providers = providers, - objects = objects, - konanHome = dokkatooExtension.konanHome.asFile, - ) - val allKotlinCompilationDetails: ListProperty = - compilationDetailsBuilder.createCompilationDetails( - kotlinProjectExtension = kotlinExtension, - ) - - // second, fetch the relevant properties of the Kotlin source sets - val sourceSetDetailsBuilder = KotlinSourceSetDetailsBuilder( - providers = providers, - objects = objects, - sourceSetScopeDefault = dokkatooExtension.sourceSetScopeDefault, - projectPath = project.path, - ) - val sourceSetDetails: NamedDomainObjectContainer = - sourceSetDetailsBuilder.createSourceSetDetails( - kotlinSourceSets = kotlinExtension.sourceSets, - allKotlinCompilationDetails = allKotlinCompilationDetails, - ) - - // for each Kotlin source set, register a Dokkatoo source set - registerDokkatooSourceSets( - dokkatooExtension = dokkatooExtension, - sourceSetDetails = sourceSetDetails, - ) - } - - /** Register a [DokkaSourceSetSpec] for each element in [sourceSetDetails] */ - private fun registerDokkatooSourceSets( - dokkatooExtension: DokkatooExtension, - sourceSetDetails: NamedDomainObjectContainer, - ) { - // proactively use 'all' so source sets will be available in users' build files if they use `named("...")` - sourceSetDetails.all details@{ - dokkatooExtension.dokkatooSourceSets.register(details = this@details) - } - } - - /** Register a single [DokkaSourceSetSpec] for [details] */ - private fun NamedDomainObjectContainer.register( - details: KotlinSourceSetDetails - ) { - val kssPlatform = details.compilations.map { values: List -> - values.map { it.kotlinPlatform } - .distinct() - .singleOrNull() ?: KotlinPlatform.Common - } - - val kssClasspath = determineClasspath(details) - - register(details.name) dss@{ - suppress.set(!details.isPublishedSourceSet()) - sourceRoots.from(details.sourceDirectories) - classpath.from(kssClasspath) - analysisPlatform.set(kssPlatform) - dependentSourceSets.addAllLater(details.dependentSourceSetIds) - } - } - - private fun determineClasspath( - details: KotlinSourceSetDetails - ): Provider { - return details.compilations.map { compilations: List -> - val classpath = objects.fileCollection() - - if (compilations.isNotEmpty()) { - compilations.fold(classpath) { acc, compilation -> - acc.from(compilation.compilationClasspath) - // can't use compileDependencyFiles, it causes weird dependency resolution errors in Android projects - //acc.from(providers.provider { compilation.compileDependencyFiles }) - } - } else { - classpath - .from(details.sourceDirectories) - .from(details.sourceDirectoriesOfDependents) - } - } - } - - @DokkatooInternalApi - companion object { - private val logger = Logging.getLogger(DokkatooKotlinAdapter::class.java) - - /** Try and get [KotlinProjectExtension], or `null` if it's not present */ - private fun ExtensionContainer.findKotlinExtension(): KotlinProjectExtension? = - try { - findByType() - // fallback to trying to get the JVM extension - // (not sure why I did this... maybe to be compatible with really old versions?) - ?: findByType() - } catch (e: Throwable) { - when (e) { - is TypeNotPresentException, - is ClassNotFoundException, - is NoClassDefFoundError -> null - - else -> throw e - } - } - - /** Get the version of the Kotlin Gradle Plugin currently used to compile the project */ - // Must be lazy, else tests fail (because the KGP plugin isn't accessible) - internal val currentKotlinToolingVersion: KotlinToolingVersion by lazy { - val kgpVersion = getKotlinPluginVersion(logger) - KotlinToolingVersion(kgpVersion) - } - } -} - - -/** - * Store the details of all [KotlinCompilation]s in a configuration cache compatible way. - * - * The compilation details may come from a multiplatform project ([KotlinMultiplatformExtension]) - * or a single-platform project ([KotlinSingleTargetExtension]). - */ -@DokkatooInternalApi -private data class KotlinCompilationDetails( - val target: String, - val kotlinPlatform: KotlinPlatform, - val allKotlinSourceSetsNames: Set, - val publishedCompilation: Boolean, - val dependentSourceSetNames: Set, - val compilationClasspath: FileCollection, - val defaultSourceSetName: String, -) - -/** Utility class, encapsulating logic for building [KotlinCompilationDetails] */ -private class KotlinCompilationDetailsBuilder( - private val objects: ObjectFactory, - private val providers: ProviderFactory, - private val konanHome: Provider, -) { - - fun createCompilationDetails( - kotlinProjectExtension: KotlinProjectExtension, - ): ListProperty { - - val details = objects.listProperty() - - details.addAll( - providers.provider { - kotlinProjectExtension - .allKotlinCompilations() - .map { compilation -> - createCompilationDetails(compilation = compilation) - } - }) - - return details - } - - /** Create a single [KotlinCompilationDetails] for [compilation] */ - private fun createCompilationDetails( - compilation: KotlinCompilation<*>, - ): KotlinCompilationDetails { - val allKotlinSourceSetsNames = - compilation.allKotlinSourceSets.map { it.name } + compilation.defaultSourceSet.name - - val dependentSourceSetNames = - compilation.defaultSourceSet.dependsOn.map { it.name } - - val compilationClasspath: FileCollection = - collectKotlinCompilationClasspath(compilation = compilation) - - return KotlinCompilationDetails( - target = compilation.target.name, - kotlinPlatform = KotlinPlatform.fromString(compilation.platformType.name), - allKotlinSourceSetsNames = allKotlinSourceSetsNames.toSet(), - publishedCompilation = compilation.isPublished(), - dependentSourceSetNames = dependentSourceSetNames.toSet(), - compilationClasspath = compilationClasspath, - defaultSourceSetName = compilation.defaultSourceSet.name - ) - } - - private fun KotlinProjectExtension.allKotlinCompilations(): Collection> = - when (this) { - is KotlinMultiplatformExtension -> targets.flatMap { it.compilations } - is KotlinSingleTargetExtension<*> -> target.compilations - else -> emptyList() // shouldn't happen? - } - - /** - * Get the [Configuration][org.gradle.api.artifacts.Configuration] names of all configurations - * used to build this [KotlinCompilation] and - * [its source sets][KotlinCompilation.kotlinSourceSets]. - */ - private fun collectKotlinCompilationClasspath( - compilation: KotlinCompilation<*>, - ): FileCollection { - val compilationClasspath = objects.fileCollection() - - // collect dependency files from 'regular' Kotlin compilations - compilationClasspath.from(providers.provider { compilation.compileDependencyFiles }) - - // apply workaround for Kotlin/Native, which will be fixed in Kotlin 2.0 - // (see KT-61559: K/N dependencies will be part of `compilation.compileDependencyFiles`) - if ( - currentKotlinToolingVersion < KotlinToolingVersion("2.0.0") - && - compilation is AbstractKotlinNativeCompilation - ) { - compilationClasspath.from( - konanHome.map { konanHome -> - kotlinNativeDependencies(konanHome, compilation.konanTarget) - } - ) - } - - return compilationClasspath - } - - private fun kotlinNativeDependencies(konanHome: File, target: KonanTarget): FileCollection { - val konanDistribution = KonanDistribution(konanHome) - - val dependencies = objects.fileCollection() - - dependencies.from(konanDistribution.stdlib) - - // Konan library files for a specific target - dependencies.from( - konanDistribution.platformLibsDir - .resolve(target.name) - .listFiles() - .orEmpty() - .filter { it.isDirectory || it.extension == "klib" } - ) - - return dependencies - } - - companion object { - - /** - * Determine if a [KotlinCompilation] is 'publishable', and so should be enabled by default - * when creating a Dokka publication. - * - * Typically, 'main' compilations are publishable and 'test' compilations should be suppressed. - * This can be overridden manually, though. - * - * @see DokkaSourceSetSpec.suppress - */ - private fun KotlinCompilation<*>.isPublished(): Boolean { - return when (this) { - is KotlinMetadataCompilation<*> -> true - - is KotlinJvmAndroidCompilation -> - androidVariant is LibraryVariant || androidVariant is ApplicationVariant - - else -> - name == MAIN_COMPILATION_NAME - } - } - } -} - - -/** - * Store the details of all [KotlinSourceSet]s in a configuration cache compatible way. - * - * @param[named] Should be [KotlinSourceSet.getName] - */ -@DokkatooInternalApi -private abstract class KotlinSourceSetDetails @Inject constructor( - private val named: String, -) : Named { - - /** Direct source sets that this source set depends on */ - abstract val dependentSourceSetIds: SetProperty - abstract val sourceDirectories: ConfigurableFileCollection - - /** _All_ source directories from any (recursively) dependant source set */ - abstract val sourceDirectoriesOfDependents: ConfigurableFileCollection - - /** The specific compilations used to build this source set */ - abstract val compilations: ListProperty - - /** Estimate if this Kotlin source set contains 'published' sources */ - fun isPublishedSourceSet(): Provider = - compilations.map { values -> - values.any { it.publishedCompilation } - } - - override fun getName(): String = named -} - -/** Utility class, encapsulating logic for building [KotlinCompilationDetails] */ -private class KotlinSourceSetDetailsBuilder( - private val sourceSetScopeDefault: Provider, - private val objects: ObjectFactory, - private val providers: ProviderFactory, - /** Used for logging */ - private val projectPath: String, -) { - - private val logger = Logging.getLogger(KotlinSourceSetDetails::class.java) - - fun createSourceSetDetails( - kotlinSourceSets: NamedDomainObjectContainer, - allKotlinCompilationDetails: ListProperty, - ): NamedDomainObjectContainer { - - val sourceSetDetails = objects.domainObjectContainer(KotlinSourceSetDetails::class) - - kotlinSourceSets.configureEach kss@{ - sourceSetDetails.register( - kotlinSourceSet = this, - allKotlinCompilationDetails = allKotlinCompilationDetails, - ) - } - - return sourceSetDetails - } - - private fun NamedDomainObjectContainer.register( - kotlinSourceSet: KotlinSourceSet, - allKotlinCompilationDetails: ListProperty, - ) { - - // TODO: Needs to respect filters. - // We probably need to change from "sourceRoots" to support "sourceFiles" - // https://github.com/Kotlin/dokka/issues/1215 - val extantSourceDirectories = providers.provider { - kotlinSourceSet.kotlin.sourceDirectories.filter { it.exists() } - } - - val compilations = allKotlinCompilationDetails.map { allCompilations -> - allCompilations.filter { compilation -> - kotlinSourceSet.name in compilation.allKotlinSourceSetsNames - } - } - - // determine the source sets IDs of _other_ source sets that _this_ source depends on. - val dependentSourceSets = providers.provider { kotlinSourceSet.dependsOn } - val dependentSourceSetIds = - providers.zip( - dependentSourceSets, - sourceSetScopeDefault, - ) { sourceSets, sourceSetScope -> - logger.info("[$projectPath] source set ${kotlinSourceSet.name} has ${sourceSets.size} dependents ${sourceSets.joinToString { it.name }}") - sourceSets.map { dependedKss -> - objects.dokkaSourceSetIdSpec(sourceSetScope, dependedKss.name) - } - } - - val sourceDirectoriesOfDependents = providers.provider { - kotlinSourceSet - .allDependentSourceSets() - .fold(objects.fileCollection()) { acc, sourceSet -> - acc.from(sourceSet.kotlin.sourceDirectories) - } - } - - register(kotlinSourceSet.name) { - this.dependentSourceSetIds.addAll(dependentSourceSetIds) - this.sourceDirectories.from(extantSourceDirectories) - this.sourceDirectoriesOfDependents.from(sourceDirectoriesOfDependents) - this.compilations.addAll(compilations) - } - } - - /** - * Return a list containing _all_ source sets that this source set depends on, - * searching recursively. - * - * @see KotlinSourceSet.dependsOn - */ - private tailrec fun KotlinSourceSet.allDependentSourceSets( - queue: Set = dependsOn.toSet(), - allDependents: List = emptyList(), - ): List { - val next = queue.firstOrNull() ?: return allDependents - return next.allDependentSourceSets( - queue = (queue - next) union next.dependsOn, - allDependents = allDependents + next, - ) - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/distributions/DokkatooConfigurationAttributes.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/distributions/DokkatooConfigurationAttributes.kt deleted file mode 100644 index a51bc69e6a..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/distributions/DokkatooConfigurationAttributes.kt +++ /dev/null @@ -1,63 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.distributions - -import org.gradle.api.Named -import org.gradle.api.artifacts.Configuration -import org.gradle.api.attributes.Attribute -import org.gradle.api.attributes.Usage -import org.gradle.api.model.ObjectFactory -import org.gradle.kotlin.dsl.named -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import javax.inject.Inject - -/** - * Gradle Configuration Attributes for sharing Dokkatoo files across subprojects. - * - * These attributes are used to tag [Configuration]s, so files can be shared between subprojects. - */ -@DokkatooInternalApi -abstract class DokkatooConfigurationAttributes -@Inject -constructor( - objects: ObjectFactory, -) { - - /** A general attribute for all [Configuration]s that are used by the Dokka Gradle plugin */ - val dokkatooBaseUsage: DokkatooBaseAttribute = objects.named("dokkatoo") - - /** for [Configuration]s that provide or consume Dokka parameter files */ - val dokkaParameters: DokkatooCategoryAttribute = objects.named("generator-parameters") - - /** for [Configuration]s that provide or consume Dokka Module files */ - val dokkaModuleFiles: DokkatooCategoryAttribute = objects.named("module-files") -// val dokkaModuleSource: DokkatooCategoryAttribute = objects.named("module-source") - - val dokkaGeneratorClasspath: DokkatooCategoryAttribute = objects.named("generator-classpath") - - val dokkaPluginsClasspath: DokkatooCategoryAttribute = objects.named("plugins-classpath") - - @DokkatooInternalApi - interface DokkatooBaseAttribute : Usage - - @DokkatooInternalApi - interface DokkatooCategoryAttribute : Named - - @DokkatooInternalApi - interface DokkaFormatAttribute : Named - - @DokkatooInternalApi - companion object { - val DOKKATOO_BASE_ATTRIBUTE = - Attribute("org.jetbrains.dokka.dokkatoo.base") - val DOKKATOO_CATEGORY_ATTRIBUTE = - Attribute("org.jetbrains.dokka.dokkatoo.category") - val DOKKA_FORMAT_ATTRIBUTE = - Attribute("org.jetbrains.dokka.dokkatoo.format") - - private inline fun Attribute(name: String): Attribute = - Attribute.of(name, T::class.java) - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/DokkaPublication.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/DokkaPublication.kt deleted file mode 100644 index ca860ecedb..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/DokkaPublication.kt +++ /dev/null @@ -1,125 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka - -import org.gradle.api.Named -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.plugins.ExtensionAware -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.tasks.* -import org.gradle.api.tasks.PathSensitivity.RELATIVE -import org.jetbrains.dokka.dokkatoo.internal.DokkaPluginParametersContainer -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.adding -import java.io.Serializable -import javax.inject.Inject - -/** - * A [DokkaPublication] describes a single Dokka output. - * - * Each Publication has its own set of Gradle tasks and [org.gradle.api.artifacts.Configuration]s. - * - * The type of site is determined by the Dokka Plugins. By default, an HTML site will be generated. - * By default, Dokka will create publications for HTML, Jekyll, and GitHub Flavoured Markdown. - */ -abstract class DokkaPublication -@DokkatooInternalApi -@Inject -constructor( - @get:Internal - val formatName: String, - - /** - * Configurations for Dokka Generator Plugins. Must be provided from - * [org.jetbrains.dokka.dokkatoo.DokkatooExtension.pluginsConfiguration]. - */ - pluginsConfiguration: DokkaPluginParametersContainer, -) : Named, Serializable, ExtensionAware { - - /** Configurations for Dokka Generator Plugins. */ - @get:Nested - val pluginsConfiguration: DokkaPluginParametersContainer = - extensions.adding("pluginsConfiguration", pluginsConfiguration) - - @Internal - override fun getName(): String = formatName - - @get:Input - abstract val enabled: Property - - @get:Input - abstract val moduleName: Property - - @get:Input - @get:Optional - abstract val moduleVersion: Property - - @get:Internal - // marked as Internal because this task does not use the directory contents, only the location - abstract val outputDir: DirectoryProperty - - /** - * Because [outputDir] must be [Internal] (so Gradle doesn't check the directory contents), - * [outputDirPath] is required so Gradle can determine if the task is up-to-date. - */ - @get:Input - // marked as an Input because a DokkaPublication is used to configure the appropriate - // DokkatooTasks, which will then - @DokkatooInternalApi - protected val outputDirPath: Provider - get() = outputDir.map { it.asFile.invariantSeparatorsPath } - - @get:Internal - // Marked as Internal because this task does not use the directory contents, only the location. - // Note that `cacheRoot` is not used by Dokka, and will probably be deprecated. - abstract val cacheRoot: DirectoryProperty - - /** - * Because [cacheRoot] must be [Internal] (so Gradle doesn't check the directory contents), - * [cacheRootPath] is required so Gradle can determine if the task is up-to-date. - */ - @get:Input - @get:Optional - @DokkatooInternalApi - protected val cacheRootPath: Provider - get() = cacheRoot.map { it.asFile.invariantSeparatorsPath } - - @get:Input - abstract val offlineMode: Property - -// /** Dokka Configuration files from other subprojects that will be merged into this Dokka Configuration */ -// @get:InputFiles -// @get:NormalizeLineEndings -// @get:PathSensitive(PathSensitivity.NAME_ONLY) -// abstract val dokkaSubprojectConfigurations: ConfigurableFileCollection - -// /** Dokka Module Configuration from other subprojects. */ -// @get:InputFiles -// @get:NormalizeLineEndings -// @get:PathSensitive(PathSensitivity.NAME_ONLY) -// abstract val dokkaModuleDescriptorFiles: ConfigurableFileCollection - - @get:Input - abstract val failOnWarning: Property - - @get:Input - abstract val delayTemplateSubstitution: Property - - @get:Input - abstract val suppressObviousFunctions: Property - - @get:InputFiles - @get:PathSensitive(RELATIVE) - abstract val includes: ConfigurableFileCollection - - @get:Input - abstract val suppressInheritedMembers: Property - - @get:Input - // TODO probably not needed any more, since Dokka Generator now runs in an isolated JVM process - abstract val finalizeCoroutines: Property -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaExternalDocumentationLinkSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaExternalDocumentationLinkSpec.kt deleted file mode 100644 index 100dedf13f..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaExternalDocumentationLinkSpec.kt +++ /dev/null @@ -1,124 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.gradle.api.Named -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.tasks.Input -import org.gradle.api.tasks.Internal -import org.intellij.lang.annotations.Language -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.Serializable -import java.net.URI -import javax.inject.Inject - -/** - * Configuration builder that allows creating links leading to externally hosted - * documentation of your dependencies. - * - * For instance, if you are using types from `kotlinx.serialization`, by default - * they will be unclickable in your documentation, as if unresolved. However, - * since API reference for `kotlinx.serialization` is also built by Dokka and is - * [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/), - * you can configure external documentation links for it, allowing Dokka to generate - * documentation links for used types, making them clickable and appear resolved. - * - * Example in Gradle Kotlin DSL: - * - * ```kotlin - * externalDocumentationLink { - * url.set(URI("https://kotlinlang.org/api/kotlinx.serialization/")) - * packageListUrl.set( - * rootProject.projectDir.resolve("serialization.package.list").toURI() - * ) - * } - * ``` - */ -abstract class DokkaExternalDocumentationLinkSpec -@DokkatooInternalApi -@Inject -constructor( - private val name: String -) : Serializable, Named { - - /** - * Root URL of documentation to link with. - * - * Dokka will do its best to automatically find `package-list` for the given URL, and link - * declarations together. - * - * It automatic resolution fails or if you want to use locally cached files instead, - * consider providing [packageListUrl]. - * - * Example: - * - * ```kotlin - * java.net.URI("https://kotlinlang.org/api/kotlinx.serialization/") - * ``` - */ - @get:Input - abstract val url: Property - - /** - * Set the value of [url]. - * - * @param[value] will be converted to a [URI] - */ - fun url(@Language("http-url-reference") value: String): Unit = - url.set(URI(value)) - - /** - * Set the value of [url]. - * - * @param[value] will be converted to a [URI] - */ - fun url(value: Provider): Unit = - url.set(value.map(::URI)) - - /** - * Specifies the exact location of a `package-list` instead of relying on Dokka - * automatically resolving it. Can also be a locally cached file to avoid network calls. - * - * Example: - * - * ```kotlin - * rootProject.projectDir.resolve("serialization.package.list").toURL() - * ``` - */ - @get:Input - abstract val packageListUrl: Property - - /** - * Set the value of [packageListUrl]. - * - * @param[value] will be converted to a [URI] - */ - fun packageListUrl(@Language("http-url-reference") value: String): Unit = - packageListUrl.set(URI(value)) - - /** - * Set the value of [packageListUrl]. - * - * @param[value] will be converted to a [URI] - */ - fun packageListUrl(value: Provider): Unit = - packageListUrl.set(value.map(::URI)) - - /** - * If enabled this link will be passed to the Dokka Generator. - * - * Defaults to `true`. - * - * @see org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec.enableKotlinStdLibDocumentationLink - * @see org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec.enableJdkDocumentationLink - * @see org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec.enableAndroidDocumentationLink - */ - @get:Input - abstract val enabled: Property - - @Internal - override fun getName(): String = name -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaGeneratorParametersSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaGeneratorParametersSpec.kt deleted file mode 100644 index d215c3cf0c..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaGeneratorParametersSpec.kt +++ /dev/null @@ -1,97 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -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.Property -import org.gradle.api.tasks.* -import org.gradle.api.tasks.PathSensitivity.RELATIVE -import org.gradle.work.NormalizeLineEndings -import org.jetbrains.dokka.dokkatoo.internal.DokkaPluginParametersContainer -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.adding -import org.jetbrains.dokka.dokkatoo.internal.domainObjectContainer -import javax.inject.Inject - -/** - * Parameters used to run Dokka Generator to produce either a Publication or a Module. - * - * - */ -abstract class DokkaGeneratorParametersSpec -@DokkatooInternalApi -@Inject -constructor( - objects: ObjectFactory, - /** - * Configurations for Dokka Generator Plugins. Must be provided from - * [org.jetbrains.dokka.dokkatoo.dokka.DokkaPublication.pluginsConfiguration]. - */ - @get:Nested - val pluginsConfiguration: DokkaPluginParametersContainer, -) : ExtensionAware { - -// /** Dokka Configuration files from other subprojects that will be merged into this Dokka Configuration */ -// @get:InputFiles -// //@get:NormalizeLineEndings -// @get:PathSensitive(PathSensitivity.RELATIVE) -// @get:Optional -// abstract val dokkaSubprojectParameters: ConfigurableFileCollection - - @get:Input - abstract val failOnWarning: Property - - @get:Input - abstract val finalizeCoroutines: Property - - @get:Input - abstract val moduleName: Property - - @get:Input - @get:Optional - abstract val moduleVersion: Property - - @get:Input - abstract val offlineMode: Property - - @get:Input - abstract val suppressObviousFunctions: Property - - @get:Input - abstract val suppressInheritedMembers: Property - - @get:InputFiles - @get:PathSensitive(RELATIVE) - abstract val includes: ConfigurableFileCollection - - /** - * Classpath that contains the Dokka Generator Plugins used to modify this publication. - * - * The plugins should be configured in [org.jetbrains.dokka.dokkatoo.dokka.DokkaPublication.pluginsConfiguration]. - */ - @get:InputFiles - @get:Classpath - abstract val pluginsClasspath: ConfigurableFileCollection - - /** - * Source sets used to generate a Dokka Module. - * - * The values are not used directly in this task, but they are required to be registered as a - * task input for up-to-date checks - */ - @get:Nested - val dokkaSourceSets: NamedDomainObjectContainer = - extensions.adding("dokkaSourceSets", objects.domainObjectContainer()) - - /** Dokka Module files from other subprojects. */ - @get:InputFiles - @get:NormalizeLineEndings - @get:PathSensitive(RELATIVE) - @get:Optional - abstract val dokkaModuleFiles: ConfigurableFileCollection -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaModuleDescriptionSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaModuleDescriptionSpec.kt deleted file mode 100644 index 6043a60a51..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaModuleDescriptionSpec.kt +++ /dev/null @@ -1,53 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.gradle.api.Named -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.provider.Property -import org.gradle.api.tasks.Input -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import javax.inject.Inject - -/** - * Properties that describe a Dokka Module. - * - * These values are passed into Dokka Generator, which will aggregate all provided Modules into a - * single publication. - */ -@DokkatooInternalApi -abstract class DokkaModuleDescriptionSpec -@DokkatooInternalApi -@Inject constructor( - @get:Input - val moduleName: String, -) : Named { - - /** - * @see DokkaConfiguration.DokkaModuleDescription.sourceOutputDirectory - */ - @get:Input - abstract val sourceOutputDirectory: RegularFileProperty - - /** - * @see DokkaConfiguration.DokkaModuleDescription.includes - */ - @get:Input - abstract val includes: ConfigurableFileCollection - - /** - * File path of the subproject that determines where the Dokka Module will be placed within an - * assembled Dokka Publication. - * - * This must be a relative path, and will be appended to the root Dokka Publication directory. - * - * The Gradle project path will also be accepted ([org.gradle.api.Project.getPath]), and the - * colons `:` will be replaced with file separators `/`. - */ - @get:Input - abstract val projectPath: Property -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaPackageOptionsSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaPackageOptionsSpec.kt deleted file mode 100644 index 58ca97c3fb..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaPackageOptionsSpec.kt +++ /dev/null @@ -1,88 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("FunctionName") - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.gradle.api.provider.Property -import org.gradle.api.provider.SetProperty -import org.gradle.api.tasks.Input -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.Serializable - -/** - * Configuration builder that allows setting some options for specific packages - * matched by [matchingRegex]. - * - * Example in Gradle Kotlin DSL: - * - * ```kotlin - * tasks.dokkaHtml { - * dokkaSourceSets.configureEach { - * perPackageOption { - * matchingRegex.set(".*internal.*") - * suppress.set(true) - * } - * } - * } - * ``` - */ -abstract class DokkaPackageOptionsSpec -@DokkatooInternalApi -constructor() : - HasConfigurableVisibilityModifiers, - Serializable { - - /** - * Regular expression that is used to match the package. - * - * Default is any string: `.*`. - */ - @get:Input - abstract val matchingRegex: Property - - /** - * Whether this package should be skipped when generating documentation. - * - * Default is `false`. - */ - @get:Input - abstract val suppress: Property - - /** - * Set of visibility modifiers that should be documented. - * - * This can be used if you want to document protected/internal/private declarations within a - * specific package, as well as if you want to exclude public declarations and only document internal API. - * - * Can be configured for a whole source set, see [DokkaSourceSetSpec.documentedVisibilities]. - * - * Default is [VisibilityModifier.PUBLIC]. - */ - @get:Input - abstract override val documentedVisibilities: SetProperty - - /** - * Whether to document declarations annotated with [Deprecated]. - * - * Can be overridden on source set level by setting [DokkaSourceSetSpec.skipDeprecated]. - * - * Default is `false`. - */ - @get:Input - abstract val skipDeprecated: Property - - /** - * Whether to emit warnings about visible undocumented declarations, that is declarations from - * this package and without KDocs, after they have been filtered by [documentedVisibilities]. - * - * - * Can be overridden on source set level by setting [DokkaSourceSetSpec.reportUndocumented]. - * - * Default is `false`. - */ - @get:Input - abstract val reportUndocumented: Property -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaParametersKxs.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaParametersKxs.kt deleted file mode 100644 index ae7d543cc9..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaParametersKxs.kt +++ /dev/null @@ -1,82 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:UseSerializers( - FileAsPathStringSerializer::class, -) - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import kotlinx.serialization.KSerializer -import kotlinx.serialization.Serializable -import kotlinx.serialization.UseSerializers -import kotlinx.serialization.descriptors.PrimitiveKind -import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor -import kotlinx.serialization.descriptors.SerialDescriptor -import kotlinx.serialization.encoding.Decoder -import kotlinx.serialization.encoding.Encoder -import org.gradle.kotlin.dsl.java -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.DokkaModuleDescriptionImpl -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.File -import java.nio.file.Paths - - -// Implementations of DokkaConfiguration interfaces that can be serialized to files. -// Serialization is required because Gradle tasks can only pass data to one-another via files. - - -/** - * Any subproject can be merged into a single Dokka Publication. To do this, first it must create - * a Dokka Module. A [DokkaModuleDescriptionKxs] describes a config file for the Dokka Module that - * describes its content. This config file will be used by any aggregating project to produce - * a Dokka Publication with multiple modules. - * - * Note: this class implements [java.io.Serializable] because it is used as a - * [Gradle Property][org.gradle.api.provider.Property], and Gradle must be able to fingerprint - * property values classes using Java Serialization. - * - * All other configuration data classes also implement [java.io.Serializable] via their parent interfaces. - */ -@Serializable -@DokkatooInternalApi -data class DokkaModuleDescriptionKxs( - /** @see DokkaConfiguration.DokkaModuleDescription.name */ - val name: String, - /** - * Location of the Dokka Module directory for a subproject. - * - * @see DokkaConfiguration.DokkaModuleDescription.sourceOutputDirectory - */ - val sourceOutputDirectory: File, - /** @see DokkaConfiguration.DokkaModuleDescription.includes */ - val includes: Set, - /** @see [org.gradle.api.Project.getPath] */ - val modulePath: String, -) { - internal fun convert() = - DokkaModuleDescriptionImpl( - name = name, - relativePathToOutputDirectory = File(modulePath.removePrefix(":").replace(':', '/')), - includes = includes, - sourceOutputDirectory = sourceOutputDirectory, - ) -} - - -/** - * Serialize a [File] as an absolute, canonical file path, with - * [invariant path separators][invariantSeparatorsPath] - */ -private object FileAsPathStringSerializer : KSerializer { - override val descriptor: SerialDescriptor = - PrimitiveSerialDescriptor("java.io.File", PrimitiveKind.STRING) - - override fun deserialize(decoder: Decoder): File = - Paths.get(decoder.decodeString()).toFile() - - override fun serialize(encoder: Encoder, value: File): Unit = - encoder.encodeString(value.invariantSeparatorsPath) -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceLinkSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceLinkSpec.kt deleted file mode 100644 index 91331b0029..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceLinkSpec.kt +++ /dev/null @@ -1,110 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.tasks.Input -import org.gradle.api.tasks.Internal -import org.gradle.api.tasks.Optional -import org.intellij.lang.annotations.Language -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.Serializable -import java.net.URI - -/** - * Configuration builder that allows adding a `source` link to each signature - * which leads to [remoteUrl] with a specific line number (configurable by setting [remoteLineSuffix]), - * letting documentation readers find source code for each declaration. - * - * Example in Gradle Kotlin DSL: - * - * ```kotlin - * sourceLink { - * localDirectory.set(projectDir.resolve("src")) - * remoteUrl.set(URI("https://github.com/kotlin/dokka/tree/master/src")) - * remoteLineSuffix.set("#L") - * } - * ``` - */ -abstract class DokkaSourceLinkSpec -@DokkatooInternalApi -constructor() : Serializable { - - /** - * Path to the local source directory. The path must be relative to the root of current project. - * - * This path is used to find relative paths of the source files from which the documentation is built. - * These relative paths are then combined with the base url of a source code hosting service specified with - * the [remoteUrl] property to create source links for each declaration. - * - * Example: - * - * ```kotlin - * projectDir.resolve("src") - * ``` - */ - @get:Internal // changing contents of the directory should not invalidate the task - abstract val localDirectory: DirectoryProperty - - /** - * The relative path to [localDirectory] from the project directory. Declared as an input to invalidate the task if that path changes. - * Should not be used anywhere directly. - */ - @get:Input - @DokkatooInternalApi - protected val localDirectoryPath: Provider - get() = localDirectory.map { it.asFile.invariantSeparatorsPath } - - /** - * URL of source code hosting service that can be accessed by documentation readers, - * like GitHub, GitLab, Bitbucket, etc. This URL will be used to generate - * source code links of declarations. - * - * Example: - * - * ```kotlin - * java.net.URI("https://github.com/username/projectname/tree/master/src")) - * ``` - */ - @get:Input - abstract val remoteUrl: Property - - /** - * Set the value of [remoteUrl]. - * - * @param[value] will be converted to a [URI] - */ - fun remoteUrl(@Language("http-url-reference") value: String): Unit = - remoteUrl.set(URI(value)) - - /** - * Set the value of [remoteUrl]. - * - * @param[value] will be converted to a [URI] - */ - fun remoteUrl(value: Provider): Unit = - remoteUrl.set(value.map(::URI)) - - /** - * Suffix used to append source code line number to the URL. This will help readers navigate - * not only to the file, but to the specific line number of the declaration. - * - * The number itself will be appended to the specified suffix. For instance, - * if this property is set to `#L` and the line number is 10, resulting URL suffix - * will be `#L10` - * - * Suffixes used by popular services: - * - GitHub: `#L` - * - GitLab: `#L` - * - Bitbucket: `#lines-` - * - * Default is `#L`. - */ - @get:Optional - @get:Input - abstract val remoteLineSuffix: Property -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceSetIdSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceSetIdSpec.kt deleted file mode 100644 index d68fd713e2..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceSetIdSpec.kt +++ /dev/null @@ -1,65 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.gradle.api.Named -import org.gradle.api.model.ObjectFactory -import org.gradle.api.tasks.Input -import org.gradle.api.tasks.Internal -import org.gradle.kotlin.dsl.newInstance -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.Serializable -import javax.inject.Inject - -abstract class DokkaSourceSetIdSpec -@DokkatooInternalApi -@Inject -constructor( - /** - * Unique identifier of the scope that this source set is placed in. - * Each scope provide only unique source set names. - * - * TODO update this doc - DokkaTask doesn't represent one source set scope anymore - * - * E.g. One DokkaTask inside the Gradle plugin represents one source set scope, since there cannot be multiple - * source sets with the same name. However, a Gradle project will not be a proper scope, since there can be - * multiple DokkaTasks that contain source sets with the same name (but different configuration) - */ - @get:Input - val scopeId: String, - - @get:Input - val sourceSetName: String, -) : Named, Serializable { - - @Internal - override fun getName(): String = "$scopeId/$sourceSetName" - - override fun toString(): String = "DokkaSourceSetIdSpec($scopeId/$sourceSetName)" - - override fun equals(other: Any?): Boolean { - if (this === other) return true - if (other !is DokkaSourceSetIdSpec) return false - - if (scopeId != other.scopeId) return false - return sourceSetName == other.sourceSetName - } - - override fun hashCode(): Int { - var result = scopeId.hashCode() - result = 31 * result + sourceSetName.hashCode() - return result - } - - companion object { - - /** Utility for creating a new [DokkaSourceSetIdSpec] instance using [ObjectFactory.newInstance] */ - @DokkatooInternalApi - fun ObjectFactory.dokkaSourceSetIdSpec( - scopeId: String, - sourceSetName: String, - ): DokkaSourceSetIdSpec = newInstance(scopeId, sourceSetName) - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceSetSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceSetSpec.kt deleted file mode 100644 index fea81d2355..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/DokkaSourceSetSpec.kt +++ /dev/null @@ -1,378 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -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.Property -import org.gradle.api.provider.Provider -import org.gradle.api.provider.SetProperty -import org.gradle.api.tasks.* -import org.gradle.kotlin.dsl.java -import org.gradle.kotlin.dsl.newInstance -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetIdSpec.Companion.dokkaSourceSetIdSpec -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.adding -import org.jetbrains.dokka.dokkatoo.internal.domainObjectContainer -import java.io.Serializable -import javax.inject.Inject - -/** - * [Source set](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets) level configuration. - * - * Can be configured in the following way with Gradle Kotlin DSL: - * - * ```kotlin - * // build.gradle.kts - * - * dokkatoo { - * dokkatooSourceSets { - * // configure individual source set by name - * named("customSourceSet") { - * suppress.set(true) - * } - * - * // configure all source sets at once - * configureEach { - * reportUndocumented.set(true) - * } - * } - * } - * ``` - */ -abstract class DokkaSourceSetSpec -@DokkatooInternalApi -@Inject -constructor( - private val name: String, - private val objects: ObjectFactory, -) : - HasConfigurableVisibilityModifiers, - Named, - Serializable, - ExtensionAware { - - @Internal // will be tracked by sourceSetId - override fun getName(): String = name - - /** - * An arbitrary string used to group source sets that originate from different Gradle subprojects. - * This is primarily used by Kotlin Multiplatform projects, which can have multiple source sets - * per subproject. - * - * The default is set from [DokkatooExtension.sourceSetScopeDefault][org.jetbrains.dokka.dokkatoo.DokkatooExtension.sourceSetScopeDefault] - * - * It's unlikely that this value needs to be changed. - */ - @get:Internal // will be tracked by sourceSetId - abstract val sourceSetScope: Property - - /** - * The identifier for this source set, across all Gradle subprojects. - * - * @see sourceSetScope - * @see getName - */ - @get:Input - val sourceSetId: Provider - get() = sourceSetScope.map { scope -> objects.dokkaSourceSetIdSpec(scope, getName()) } - - /** - * Whether this source set should be skipped when generating documentation. - * - * Default is `false`. - */ - @get:Input - abstract val suppress: Property - - /** - * Display name used to refer to the source set. - * - * The name will be used both externally (for example, source set name visible to documentation readers) and - * internally (for example, for logging messages of [reportUndocumented]). - * - * By default, the value is deduced from information provided by the Kotlin Gradle plugin. - */ - @get:Input - abstract val displayName: Property - - /** - * List of Markdown files that contain - * [module and package documentation](https://kotlinlang.org/docs/reference/dokka-module-and-package-docs.html). - * - * Contents of specified files will be parsed and embedded into documentation as module and package descriptions. - * - * Example of such a file: - * - * ```markdown - * # Module kotlin-demo - * - * The module shows the Dokka usage. - * - * # Package org.jetbrains.kotlin.demo - * - * Contains assorted useful stuff. - * - * ## Level 2 heading - * - * Text after this heading is also part of documentation for `org.jetbrains.kotlin.demo` - * - * # Package org.jetbrains.kotlin.demo2 - * - * Useful stuff in another package. - * ``` - */ - @get:InputFiles - @get:Optional - @get:PathSensitive(PathSensitivity.RELATIVE) - abstract val includes: ConfigurableFileCollection - - /** - * Set of visibility modifiers that should be documented. - * - * This can be used if you want to document protected/internal/private declarations, - * as well as if you want to exclude public declarations and only document internal API. - * - * Can be configured on per-package basis, see [DokkaPackageOptionsSpec.documentedVisibilities]. - * - * Default is [VisibilityModifier.PUBLIC]. - */ - @get:Input - abstract override val documentedVisibilities: SetProperty - - /** - * Specifies source sets that current source set depends on. - * - * Among other things, this information is needed to resolve - * [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html) declarations. - * - * By default, the values are deduced from information provided by the Kotlin Gradle plugin. - */ - @get:Nested - val dependentSourceSets: NamedDomainObjectContainer = - extensions.adding("dependentSourceSets", objects.domainObjectContainer()) - - /** - * Classpath for analysis and interactive samples. - * - * Useful if some types that come from dependencies are not resolved/picked up automatically. - * Property accepts both `.jar` and `.klib` files. - * - * By default, classpath is deduced from information provided by the Kotlin Gradle plugin. - */ - @get:Classpath - @get:Optional - abstract val classpath: ConfigurableFileCollection - - /** - * Source code roots to be analyzed and documented. - * Accepts directories and individual `.kt` / `.java` files. - * - * By default, source roots are deduced from information provided by the Kotlin Gradle plugin. - */ - @get:InputFiles - @get:PathSensitive(PathSensitivity.RELATIVE) - abstract val sourceRoots: ConfigurableFileCollection - - /** - * List of directories or files that contain sample functions which are referenced via - * [`@sample`](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) KDoc tag. - */ - @get:InputFiles - @get:Optional - @get:PathSensitive(PathSensitivity.RELATIVE) - abstract val samples: ConfigurableFileCollection - - /** - * Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs - * after they have been filtered by [documentedVisibilities]. - * - * Can be overridden for a specific package by setting [DokkaPackageOptionsSpec.reportUndocumented]. - * - * Default is `false`. - */ - @get:Input - abstract val reportUndocumented: Property - - /** - * Specifies the location of the project source code on the Web. If provided, Dokka generates - * "source" links for each declaration. See [DokkaSourceLinkSpec] for more details. - * - * Prefer using [sourceLink] action/closure for adding source links. - * - * @see sourceLink - */ - @get:Nested - abstract val sourceLinks: DomainObjectSet - - /** - * Allows to customize documentation generation options on a per-package basis. - * - * @see DokkaPackageOptionsSpec for details - */ - @get:Nested - abstract val perPackageOptions: DomainObjectSet - - /** - * Allows linking to Dokka/Javadoc documentation of the project's dependencies. - */ - @get:Nested - val externalDocumentationLinks: NamedDomainObjectContainer = - extensions.adding("externalDocumentationLinks", objects.domainObjectContainer()) - - /** - * Platform to be used for setting up code analysis and samples. - * - * The default value is deduced from information provided by the Kotlin Gradle plugin. - */ - @get:Input - abstract val analysisPlatform: Property - - /** - * Whether to skip packages that contain no visible declarations after - * various filters have been applied. - * - * For instance, if [skipDeprecated] is set to `true` and your package contains only - * deprecated declarations, it will be considered to be empty. - * - * Default is `true`. - */ - @get:Input - abstract val skipEmptyPackages: Property - - /** - * Whether to document declarations annotated with [Deprecated]. - * - * Can be overridden on package level by setting [DokkaPackageOptionsSpec.skipDeprecated]. - * - * Default is `false`. - */ - @get:Input - abstract val skipDeprecated: Property - - /** - * Directories or individual files that should be suppressed, meaning declarations from them - * will be not documented. - * - * Will be concatenated with generated files if [suppressGeneratedFiles] is set to `false`. - */ - @get:InputFiles - @get:PathSensitive(PathSensitivity.RELATIVE) - abstract val suppressedFiles: ConfigurableFileCollection - - /** - * Whether to document/analyze generated files. - * - * Generated files are expected to be present under `{project}/{buildDir}/generated` directory. - * If set to `true`, it effectively adds all files from that directory to [suppressedFiles], so - * you can configure it manually. - * - * Default is `true`. - */ - @get:Input - abstract val suppressGeneratedFiles: Property - - /** - * Whether to generate external documentation links that lead to API reference documentation for - * Kotlin's standard library when declarations from it are used. - * - * Default is `true`, meaning links will be generated. - * - * @see externalDocumentationLinks - */ - @get:Input - abstract val enableKotlinStdLibDocumentationLink: Property - - /** - * Whether to generate external documentation links to JDK's Javadocs when declarations from it - * are used. - * - * The version of JDK Javadocs is determined by [jdkVersion] property. - * - * Default is `true`, meaning links will be generated. - * - * @see externalDocumentationLinks - */ - @get:Input - abstract val enableJdkDocumentationLink: Property - - /** - * Whether to generate external documentation links for Android SDK API reference when - * declarations from it are used. - * - * Only relevant in Android projects, ignored otherwise. - * - * Default is `false`, meaning links will not be generated. - * - * @see externalDocumentationLinks - */ - @get:Input - abstract val enableAndroidDocumentationLink: Property - - /** - * [Kotlin language version](https://kotlinlang.org/docs/compatibility-modes.html) - * used for setting up analysis and [`@sample`](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) - * environment. - * - * By default, the latest language version available to Dokka's embedded compiler will be used. - */ - @get:Input - @get:Optional - abstract val languageVersion: Property - - /** - * [Kotlin API version](https://kotlinlang.org/docs/compatibility-modes.html) - * used for setting up analysis and [`@sample`](https://kotlinlang.org/docs/kotlin-doc.html#sample-identifier) - * environment. - * - * By default, it will be deduced from [languageVersion]. - */ - @get:Input - @get:Optional - abstract val apiVersion: Property - - /** - * JDK version to use when generating external documentation links for Java types. - * - * For instance, if you use [java.util.UUID] from JDK in some public declaration signature, - * and this property is set to `8`, Dokka will generate an external documentation link - * to [JDK 8 Javadocs](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html) for it. - * - * Default is JDK 8. - */ - @get:Input - abstract val jdkVersion: Property - - /** - * Configure and add a new source link to [sourceLinks]. - * - * @see DokkaSourceLinkSpec - */ - fun sourceLink(action: Action) { - sourceLinks.add( - objects.newInstance(DokkaSourceLinkSpec::class).also { - action.execute(it) - } - ) - } - - /** - * Action for configuring package options, appending to [perPackageOptions]. - * - * @see DokkaPackageOptionsSpec - */ - fun perPackageOption(action: Action) { - perPackageOptions.add( - objects.newInstance(DokkaPackageOptionsSpec::class).also { - action.execute(it) - } - ) - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/HasConfigurableVisibilityModifiers.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/HasConfigurableVisibilityModifiers.kt deleted file mode 100644 index 3b4c6582b6..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/HasConfigurableVisibilityModifiers.kt +++ /dev/null @@ -1,18 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.gradle.api.provider.SetProperty -import org.gradle.api.tasks.Input - -internal interface HasConfigurableVisibilityModifiers { - - @get:Input - val documentedVisibilities: SetProperty - - /** Sets [documentedVisibilities] (overrides any previously set values). */ - fun documentedVisibilities(vararg visibilities: VisibilityModifier): Unit = - documentedVisibilities.set(visibilities.asList()) -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/KotlinPlatform.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/KotlinPlatform.kt deleted file mode 100644 index a7387c5cc7..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/KotlinPlatform.kt +++ /dev/null @@ -1,58 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.jetbrains.dokka.Platform - - -/** - * The Kotlin - * - * @see org.jetbrains.dokka.Platform - * @param[displayName] The display name, eventually used in the rendered Dokka publication. - */ -enum class KotlinPlatform( - internal val displayName: String -) { - AndroidJVM("androidJvm"), - Common("common"), - JS("js"), - JVM("jvm"), - Native("native"), - WASM("wasm"), - ; - - companion object { - internal val values: Set = values().toSet() - - val DEFAULT: KotlinPlatform = JVM - - fun fromString(key: String): KotlinPlatform { - val keyMatch = values.firstOrNull { - it.name.equals(key, ignoreCase = true) || it.displayName.equals(key, ignoreCase = true) - } - if (keyMatch != null) { - return keyMatch - } - - return when (key.lowercase()) { - "android" -> AndroidJVM - "metadata" -> Common - else -> error("Unrecognized platform: $key") - } - } - - // Not defined as a property to try and minimize the dependency on Dokka Core types - internal val KotlinPlatform.dokkaType: Platform - get() = - when (this) { - AndroidJVM, JVM -> Platform.jvm - JS -> Platform.js - WASM -> Platform.wasm - Native -> Platform.native - Common -> Platform.common - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/VisibilityModifier.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/VisibilityModifier.kt deleted file mode 100644 index 2b2bb94b9d..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/VisibilityModifier.kt +++ /dev/null @@ -1,46 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters - -import org.jetbrains.dokka.DokkaConfiguration - -/** - * Denotes the - * [visibility modifier](https://kotlinlang.org/docs/visibility-modifiers.html) - * of a source code elements. - * - * @see org.jetbrains.dokka.DokkaConfiguration.Visibility - */ -enum class VisibilityModifier { - /** `public` modifier for Java, default visibility for Kotlin */ - PUBLIC, - - /** `private` modifier for both Kotlin and Java */ - PRIVATE, - - /** `protected` modifier for both Kotlin and Java */ - PROTECTED, - - /** Kotlin-specific `internal` modifier */ - INTERNAL, - - /** Java-specific package-private visibility (no modifier) */ - PACKAGE, - ; - - companion object { - internal val entries: Set = values().toSet() - - // Not defined as a property to try and minimize the dependency on Dokka Core types - internal val VisibilityModifier.dokkaType: DokkaConfiguration.Visibility - get() = when (this) { - PUBLIC -> DokkaConfiguration.Visibility.PUBLIC - PRIVATE -> DokkaConfiguration.Visibility.PRIVATE - PROTECTED -> DokkaConfiguration.Visibility.PROTECTED - INTERNAL -> DokkaConfiguration.Visibility.INTERNAL - PACKAGE -> DokkaConfiguration.Visibility.PACKAGE - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaModuleDescriptionBuilder.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaModuleDescriptionBuilder.kt deleted file mode 100644 index beffe6d354..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaModuleDescriptionBuilder.kt +++ /dev/null @@ -1,37 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters.builders - -import org.jetbrains.dokka.DokkaModuleDescriptionImpl -import org.jetbrains.dokka.DokkaSourceSetImpl -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaModuleDescriptionSpec -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.File - -/** - * Convert the Gradle-focused [DokkaModuleDescriptionSpec] into a [DokkaSourceSetImpl] instance, - * which will be passed to Dokka Generator. - * - * The conversion is defined in a separate class to try and prevent classes from Dokka Generator - * leaking into the public API. - */ -// to be used to fix https://github.com/adamko-dev/dokkatoo/issues/67 -@DokkatooInternalApi -internal object DokkaModuleDescriptionBuilder { - - fun build( - spec: DokkaModuleDescriptionSpec, - includes: Set, - sourceOutputDirectory: File, - ): DokkaModuleDescriptionImpl = - DokkaModuleDescriptionImpl( - name = spec.name, - relativePathToOutputDirectory = File( - spec.projectPath.get().removePrefix(":").replace(':', '/') - ), - includes = includes, - sourceOutputDirectory = sourceOutputDirectory, - ) -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaParametersBuilder.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaParametersBuilder.kt deleted file mode 100644 index e8c1b8adad..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaParametersBuilder.kt +++ /dev/null @@ -1,79 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters.builders - -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.DokkaConfigurationImpl -import org.jetbrains.dokka.DokkaSourceSetImpl -import org.jetbrains.dokka.PluginConfigurationImpl -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaGeneratorParametersSpec -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaModuleDescriptionKxs -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaPluginParametersBaseSpec -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.File - -/** - * Convert the Gradle-focused [DokkaGeneratorParametersSpec] into a [DokkaSourceSetImpl] instance, - * which will be passed to Dokka Generator. - * - * The conversion is defined in a separate class to try and prevent classes from Dokka Generator - * leaking into the public API. - */ -@DokkatooInternalApi -internal object DokkaParametersBuilder { - - fun build( - spec: DokkaGeneratorParametersSpec, - delayTemplateSubstitution: Boolean, - modules: List, - outputDirectory: File, - cacheDirectory: File? = null, - ): DokkaConfiguration { - val moduleName = spec.moduleName.get() - val moduleVersion = spec.moduleVersion.orNull?.takeIf { it != "unspecified" } - val offlineMode = spec.offlineMode.get() - val sourceSets = DokkaSourceSetBuilder.buildAll(spec.dokkaSourceSets) - val failOnWarning = spec.failOnWarning.get() - val suppressObviousFunctions = spec.suppressObviousFunctions.get() - val suppressInheritedMembers = spec.suppressInheritedMembers.get() - val finalizeCoroutines = spec.finalizeCoroutines.get() - val pluginsConfiguration = spec.pluginsConfiguration.toSet() - - val pluginsClasspath = spec.pluginsClasspath.files.toList() - val includes = spec.includes.files - - return DokkaConfigurationImpl( - moduleName = moduleName, - moduleVersion = moduleVersion, - outputDir = outputDirectory, - cacheRoot = cacheDirectory, - offlineMode = offlineMode, - sourceSets = sourceSets, - pluginsClasspath = pluginsClasspath, - pluginsConfiguration = pluginsConfiguration.map(::build), - modules = modules.map(DokkaModuleDescriptionKxs::convert), -// modules = modules.map { -// it.convert( -// moduleDescriptionFiles.get(it.name) -// ?: error("missing module description files for ${it.name}") -// ) -// }, - failOnWarning = failOnWarning, - delayTemplateSubstitution = delayTemplateSubstitution, - suppressObviousFunctions = suppressObviousFunctions, - includes = includes, - suppressInheritedMembers = suppressInheritedMembers, - finalizeCoroutines = finalizeCoroutines, - ) - } - - private fun build(spec: DokkaPluginParametersBaseSpec): PluginConfigurationImpl { - return PluginConfigurationImpl( - fqPluginName = spec.pluginFqn, - serializationFormat = DokkaConfiguration.SerializationFormat.JSON, - values = spec.jsonEncode(), - ) - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaSourceSetBuilder.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaSourceSetBuilder.kt deleted file mode 100644 index d8b47d1b70..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/parameters/builders/DokkaSourceSetBuilder.kt +++ /dev/null @@ -1,116 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.parameters.builders - - -import org.gradle.api.logging.Logging -import org.jetbrains.dokka.* -import org.jetbrains.dokka.dokkatoo.dokka.parameters.* -import org.jetbrains.dokka.dokkatoo.dokka.parameters.KotlinPlatform.Companion.dokkaType -import org.jetbrains.dokka.dokkatoo.dokka.parameters.VisibilityModifier.Companion.dokkaType -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.mapNotNullToSet -import org.jetbrains.dokka.dokkatoo.internal.mapToSet - - -/** - * Convert the Gradle-focused [DokkaSourceSetSpec] into a [DokkaSourceSetImpl] instance, which - * will be passed to Dokka Generator. - * - * The conversion is defined in a separate class to try and prevent classes from Dokka Generator - * leaking into the public API. - */ -@DokkatooInternalApi -internal object DokkaSourceSetBuilder { - - private val logger = Logging.getLogger(DokkaParametersBuilder::class.java) - - fun buildAll(sourceSets: Set): List { - - val suppressedSourceSetIds = sourceSets.mapNotNullToSet { - val suppressed = it.suppress.get() - val sourceSetId = it.sourceSetId.get() - if (suppressed) { - logger.info("Dokka source set $sourceSetId is suppressed") - sourceSetId - } else { - logger.info("Dokka source set $sourceSetId isn't suppressed") - null - } - } - - val enabledSourceSets = sourceSets.filter { it.sourceSetId.get() !in suppressedSourceSetIds } - - return enabledSourceSets.map { build(it, suppressedSourceSetIds) } - } - - private fun build( - spec: DokkaSourceSetSpec, - suppressedSourceSetIds: Set, - ): DokkaSourceSetImpl { - - val dependentSourceSets = - (spec.dependentSourceSets subtract suppressedSourceSetIds).mapToSet(::build) - - return DokkaSourceSetImpl( - // properties - analysisPlatform = spec.analysisPlatform.get().dokkaType, - apiVersion = spec.apiVersion.orNull, - dependentSourceSets = dependentSourceSets, - displayName = spec.displayName.get(), - documentedVisibilities = spec.documentedVisibilities.get().mapToSet { it.dokkaType }, - externalDocumentationLinks = spec.externalDocumentationLinks.mapNotNullToSet(::build), - jdkVersion = spec.jdkVersion.get(), - languageVersion = spec.languageVersion.orNull, - noJdkLink = !spec.enableJdkDocumentationLink.get(), - noStdlibLink = !spec.enableKotlinStdLibDocumentationLink.get(), - perPackageOptions = spec.perPackageOptions.map(::build), - reportUndocumented = spec.reportUndocumented.get(), - skipDeprecated = spec.skipDeprecated.get(), - skipEmptyPackages = spec.skipEmptyPackages.get(), - sourceLinks = spec.sourceLinks.mapToSet { build(it) }, - sourceSetID = build(spec.sourceSetId.get()), - - // files - classpath = spec.classpath.files.toList(), - includes = spec.includes.files, - samples = spec.samples.files, - sourceRoots = spec.sourceRoots.files, - suppressedFiles = spec.suppressedFiles.files, - ) - } - - private fun build(spec: DokkaExternalDocumentationLinkSpec): ExternalDocumentationLinkImpl? { - if (!spec.enabled.getOrElse(true)) return null - - return ExternalDocumentationLinkImpl( - url = spec.url.get().toURL(), - packageListUrl = spec.packageListUrl.get().toURL(), - ) - } - - private fun build(spec: DokkaPackageOptionsSpec): PackageOptionsImpl = - PackageOptionsImpl( - matchingRegex = spec.matchingRegex.get(), - documentedVisibilities = spec.documentedVisibilities.get().mapToSet { it.dokkaType }, - reportUndocumented = spec.reportUndocumented.get(), - skipDeprecated = spec.skipDeprecated.get(), - suppress = spec.suppress.get(), - includeNonPublic = DokkaDefaults.includeNonPublic, - ) - - private fun build(spec: DokkaSourceSetIdSpec): DokkaSourceSetID = - DokkaSourceSetID( - scopeId = spec.scopeId, - sourceSetName = spec.sourceSetName - ) - - private fun build(spec: DokkaSourceLinkSpec): SourceLinkDefinitionImpl = - SourceLinkDefinitionImpl( - localDirectory = spec.localDirectory.asFile.get().invariantSeparatorsPath, - remoteUrl = spec.remoteUrl.get().toURL(), - remoteLineSuffix = spec.remoteLineSuffix.orNull, - ) -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaHtmlPluginParameters.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaHtmlPluginParameters.kt deleted file mode 100644 index 59cd72025d..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaHtmlPluginParameters.kt +++ /dev/null @@ -1,133 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.plugins - -import kotlinx.serialization.json.buildJsonObject -import kotlinx.serialization.json.putJsonArray -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.provider.Property -import org.gradle.api.tasks.* -import org.gradle.api.tasks.PathSensitivity.RELATIVE -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.addAll -import org.jetbrains.dokka.dokkatoo.internal.putIfNotNull -import javax.inject.Inject - - -/** - * Configuration for Dokka's base HTML format - * - * [More information is available in the Dokka docs.](https://kotlinlang.org/docs/dokka-html.html#configuration) - */ -abstract class DokkaHtmlPluginParameters -@DokkatooInternalApi -@Inject -constructor( - name: String -) : DokkaPluginParametersBaseSpec( - name, - DOKKA_HTML_PLUGIN_FQN, -) { - - /** - * List of paths for image assets to be bundled with documentation. - * The image assets can have any file extension. - * - * For more information, see - * [Customizing assets](https://kotlinlang.org/docs/dokka-html.html#customize-assets). - * - * Be aware that files will be copied as-is to a specific directory inside the assembled Dokka - * publication. This means that any relative paths must be written in such a way that they will - * work _after_ the files are moved into the publication. - * - * It's best to try and mirror Dokka's directory structure in the source files, which can help - * IDE inspections. - */ - @get:InputFiles - @get:PathSensitive(RELATIVE) - @get:Optional - abstract val customAssets: ConfigurableFileCollection - - /** - * List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. - * - * For more information, see - * [Customizing assets](https://kotlinlang.org/docs/dokka-html.html#customize-assets). - * - * Be aware that files will be copied as-is to a specific directory inside the assembled Dokka - * publication. This means that any relative paths must be written in such a way that they will - * work _after_ the files are moved into the publication. - * - * It's best to try and mirror Dokka's directory structure in the source files, which can help - * IDE inspections. - */ - @get:InputFiles - @get:PathSensitive(RELATIVE) - @get:Optional - abstract val customStyleSheets: ConfigurableFileCollection - - /** - * This is a boolean option. If set to `true`, Dokka renders properties/functions and inherited - * properties/inherited functions separately. - * - * This is disabled by default. - */ - @get:Input - @get:Optional - abstract val separateInheritedMembers: Property - - /** - * This is a boolean option. If set to `true`, Dokka merges declarations that are not declared as - * [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), but have the - * same fully qualified name. This can be useful for legacy codebases. - * - * This is disabled by default. - */ - @get:Input - @get:Optional - abstract val mergeImplicitExpectActualDeclarations: Property - - /** The text displayed in the footer. */ - @get:Input - @get:Optional - abstract val footerMessage: Property - - /** - * Path to the directory containing custom HTML templates. - * - * For more information, see [Templates](https://kotlinlang.org/docs/dokka-html.html#templates). - */ - @get:InputDirectory - @get:PathSensitive(RELATIVE) - @get:Optional - abstract val templatesDir: DirectoryProperty - - override fun jsonEncode(): String = - buildJsonObject { - putJsonArray("customAssets") { - addAll(customAssets.files) - } - putJsonArray("customStyleSheets") { - addAll(customStyleSheets.files) - } - putIfNotNull("separateInheritedMembers", separateInheritedMembers.orNull) - putIfNotNull( - "mergeImplicitExpectActualDeclarations", - mergeImplicitExpectActualDeclarations.orNull - ) - putIfNotNull("footerMessage", footerMessage.orNull) - putIfNotNull("footerMessage", footerMessage.orNull) - putIfNotNull( - "templatesDir", - templatesDir.orNull?.asFile?.canonicalFile?.invariantSeparatorsPath - ) - }.toString() - - companion object { - const val DOKKA_HTML_PARAMETERS_NAME = "html" - const val DOKKA_HTML_PLUGIN_FQN = "org.jetbrains.dokka.base.DokkaBase" - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec.kt deleted file mode 100644 index 7209ff2f97..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaPluginParametersBaseSpec.kt +++ /dev/null @@ -1,36 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.plugins - -import org.gradle.api.Named -import org.gradle.api.tasks.Input -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.Serializable -import javax.inject.Inject - -/** - * Base class for defining Dokka Plugin configuration. - * - * This class should not be instantiated directly. Instead, use a subclass, or create plugin - * parameters dynamically using [DokkaPluginParametersBuilder]. - * - * [More information about Dokka Plugins is available in the Dokka docs.](https://kotlinlang.org/docs/dokka-plugins.html) - * - * @param[pluginFqn] Fully qualified classname of the Dokka Plugin - */ -abstract class DokkaPluginParametersBaseSpec -@DokkatooInternalApi -@Inject -constructor( - private val name: String, - @get:Input - open val pluginFqn: String, -) : Serializable, Named { - - abstract fun jsonEncode(): String // to be implemented by subclasses - - @Input - override fun getName(): String = name -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder.kt deleted file mode 100644 index 7d5f18ddbd..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaPluginParametersBuilder.kt +++ /dev/null @@ -1,241 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.plugins - -import kotlinx.serialization.json.JsonArray -import kotlinx.serialization.json.JsonElement -import kotlinx.serialization.json.JsonObject -import kotlinx.serialization.json.JsonPrimitive -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.model.ObjectFactory -import org.gradle.api.provider.ListProperty -import org.gradle.api.provider.MapProperty -import org.gradle.api.provider.Provider -import org.gradle.api.tasks.* -import org.gradle.api.tasks.PathSensitivity.RELATIVE -import org.gradle.kotlin.dsl.containerWithType -import org.gradle.kotlin.dsl.listProperty -import org.gradle.kotlin.dsl.mapProperty -import org.jetbrains.dokka.dokkatoo.internal.DokkaPluginParametersContainer -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import java.io.File -import javax.inject.Inject - - -/** - * Dynamically create some configuration to control the behaviour of a Dokka Plugin. - * - * @param[pluginFqn] The fully-qualified name of a Dokka Plugin. For example, the FQN of the - * [Dokka Base plugin](https://github.com/Kotlin/dokka/tree/master/plugins/base#readme) - * is `org.jetbrains.dokka.base.DokkaBase` - */ -fun DokkaPluginParametersContainer.pluginParameters( - pluginFqn: String, - configure: DokkaPluginParametersBuilder.() -> Unit -) { - containerWithType(DokkaPluginParametersBuilder::class) - .maybeCreate(pluginFqn) - .configure() -} - - -/** - * Dynamically create some configuration to control the behaviour of a Dokka Plugin. - * - * This type of builder is necessary to respect - * [Gradle incremental build annotations](https://docs.gradle.org/current/userguide/incremental_build.html#sec:task_input_output_annotations). - * - * @param[pluginFqn] The fully-qualified name of a Dokka Plugin. For example, the Dokka Base plugin's FQN is `org.jetbrains.dokka.base.DokkaBase` - */ -abstract class DokkaPluginParametersBuilder -@Inject -@DokkatooInternalApi -constructor( - name: String, - @get:Input - override val pluginFqn: String, - - @Internal - internal val objects: ObjectFactory, -) : DokkaPluginParametersBaseSpec(name, pluginFqn) { - - @get:Nested - internal val properties = PluginConfigValue.Properties(objects.mapProperty()) - - @Internal - override fun jsonEncode(): String = properties.convertToJson().toString() - - companion object { - private fun PluginConfigValue.convertToJson(): JsonElement = - when (this) { - is PluginConfigValue.DirectoryValue -> directory.asFile.orNull.convertToJson() - is PluginConfigValue.FileValue -> file.asFile.orNull.convertToJson() - is PluginConfigValue.FilesValue -> JsonArray(files.files.map { it.convertToJson() }) - - is PluginConfigValue.BooleanValue -> JsonPrimitive(boolean) - is PluginConfigValue.NumberValue -> JsonPrimitive(number) - is PluginConfigValue.StringValue -> JsonPrimitive(string) - - is PluginConfigValue.Properties -> - JsonObject(values.get().mapValues { (_, value) -> value.convertToJson() }) - - is PluginConfigValue.Values -> - JsonArray(values.get().map { it.convertToJson() }) - } - - /** Creates a [JsonPrimitive] from the given [File]. */ - private fun File?.convertToJson(): JsonPrimitive = - JsonPrimitive(this?.canonicalFile?.invariantSeparatorsPath) - } -} - - -fun DokkaPluginParametersBuilder.files( - propertyName: String, - filesConfig: ConfigurableFileCollection.() -> Unit -) { - val files = objects.fileCollection() - files.filesConfig() - properties.values.put(propertyName, PluginConfigValue.FilesValue(files)) -} - -//region Primitive Properties -fun DokkaPluginParametersBuilder.property(propertyName: String, value: String) { - properties.values.put(propertyName, PluginConfigValue(value)) -} - -fun DokkaPluginParametersBuilder.property(propertyName: String, value: Number) { - properties.values.put(propertyName, PluginConfigValue(value)) -} - -fun DokkaPluginParametersBuilder.property(propertyName: String, value: Boolean) { - properties.values.put(propertyName, PluginConfigValue(value)) -} - -@JvmName("stringProperty") -fun DokkaPluginParametersBuilder.property(propertyName: String, provider: Provider) { - properties.values.put(propertyName, provider.map { PluginConfigValue(it) }) -} - -@JvmName("numberProperty") -fun DokkaPluginParametersBuilder.property(propertyName: String, provider: Provider) { - properties.values.put(propertyName, provider.map { PluginConfigValue(it) }) -} - -@JvmName("booleanProperty") -fun DokkaPluginParametersBuilder.property( - propertyName: String, - provider: Provider -) { - properties.values.put(propertyName, provider.map { PluginConfigValue(it) }) -} -//endregion - - -//region List Properties -fun DokkaPluginParametersBuilder.properties( - propertyName: String, - build: PluginConfigValue.Values.() -> Unit -) { - val values = PluginConfigValue.Values(objects.listProperty()) - values.build() - properties.values.put(propertyName, values) -} - -fun PluginConfigValue.Values.add(value: String) = - values.add(PluginConfigValue(value)) - -fun PluginConfigValue.Values.add(value: Number) = - values.add(PluginConfigValue(value)) - -fun PluginConfigValue.Values.add(value: Boolean) = - values.add(PluginConfigValue(value)) - -@JvmName("addString") -fun PluginConfigValue.Values.add(value: Provider) = - values.add(PluginConfigValue(value)) - -@JvmName("addNumber") -fun PluginConfigValue.Values.add(value: Provider) = - values.add(PluginConfigValue(value)) - -@JvmName("addBoolean") -fun PluginConfigValue.Values.add(value: Provider) = - values.add(PluginConfigValue(value)) -//endregion - - -sealed interface PluginConfigValue { - - /** An input file */ - class FileValue( - @InputFile - @PathSensitive(RELATIVE) - val file: RegularFileProperty, - ) : PluginConfigValue - - /** Input files and directories */ - class FilesValue( - @InputFiles - @PathSensitive(RELATIVE) - val files: ConfigurableFileCollection, - ) : PluginConfigValue - - /** An input directory */ - class DirectoryValue( - @InputDirectory - @PathSensitive(RELATIVE) - val directory: DirectoryProperty, - ) : PluginConfigValue - - /** Key-value properties. Analogous to a [JsonObject]. */ - class Properties( - @Nested - val values: MapProperty - ) : PluginConfigValue - - /** Multiple values. Analogous to a [JsonArray]. */ - class Values( - @Nested - val values: ListProperty - ) : PluginConfigValue - - sealed interface Primitive : PluginConfigValue - - /** A basic [String] value */ - class StringValue(@Input val string: String) : Primitive - - /** A basic [Number] value */ - class NumberValue(@Input val number: Number) : Primitive - - /** A basic [Boolean] value */ - class BooleanValue(@Input val boolean: Boolean) : Primitive -} - -fun PluginConfigValue(value: String) = - PluginConfigValue.StringValue(value) - -fun PluginConfigValue(value: Number) = - PluginConfigValue.NumberValue(value) - -fun PluginConfigValue(value: Boolean) = - PluginConfigValue.BooleanValue(value) - -@Suppress("FunctionName") -@JvmName("PluginConfigStringValue") -fun PluginConfigValue(value: Provider): Provider = - value.map { PluginConfigValue(it) } - -@Suppress("FunctionName") -@JvmName("PluginConfigNumberValue") -fun PluginConfigValue(value: Provider): Provider = - value.map { PluginConfigValue(it) } - -@Suppress("FunctionName") -@JvmName("PluginConfigBooleanValue") -fun PluginConfigValue(value: Provider): Provider = - value.map { PluginConfigValue(it) } diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaVersioningPluginParameters.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaVersioningPluginParameters.kt deleted file mode 100644 index 5965c6b973..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/dokka/plugins/DokkaVersioningPluginParameters.kt +++ /dev/null @@ -1,105 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.dokka.plugins - -import kotlinx.serialization.json.buildJsonObject -import kotlinx.serialization.json.putJsonArray -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.provider.ListProperty -import org.gradle.api.provider.Property -import org.gradle.api.tasks.* -import org.gradle.api.tasks.PathSensitivity.RELATIVE -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.addAll -import org.jetbrains.dokka.dokkatoo.internal.addAllIfNotNull -import org.jetbrains.dokka.dokkatoo.internal.putIfNotNull -import javax.inject.Inject - - -/** - * Configuration for - * [Dokka's Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning#readme). - * - * The versioning plugin provides the ability to host documentation for multiple versions of your - * library/application with seamless switching between them. This, in turn, provides a better - * experience for your users. - * - * Note: The versioning plugin only works with Dokka's HTML format. - */ -abstract class DokkaVersioningPluginParameters -@DokkatooInternalApi -@Inject -constructor( - name: String, -) : DokkaPluginParametersBaseSpec( - name, - DOKKA_VERSIONING_PLUGIN_FQN, -) { - - /** - * The version of your application/library that documentation is going to be generated for. - * This will be the version shown in the dropdown menu. - */ - @get:Input - @get:Optional - abstract val version: Property - - /** - * An optional list of strings that represents the order that versions should appear in the - * dropdown menu. - * - * Must match [version] string exactly. The first item in the list is at the top of the dropdown. - */ - @get:Input - @get:Optional - abstract val versionsOrdering: ListProperty - - /** - * An optional path to a parent folder that contains other documentation versions. - * It requires a specific directory structure. - * - * For more information, see - * [Directory structure](https://github.com/Kotlin/dokka/blob/master/plugins/versioning/README.md#directory-structure). - */ - @get:InputDirectory - @get:PathSensitive(RELATIVE) - @get:Optional - abstract val olderVersionsDir: DirectoryProperty - - /** - * An optional list of paths to other documentation versions. It must point to Dokka's outputs - * directly. This is useful if different versions can't all be in the same directory. - */ - @get:InputFiles - @get:PathSensitive(RELATIVE) - @get:Optional - abstract val olderVersions: ConfigurableFileCollection - - /** - * An optional boolean value indicating whether to render the navigation dropdown on all pages. - * - * Set to `true` by default. - */ - @get:Input - @get:Optional - abstract val renderVersionsNavigationOnAllPages: Property - - override fun jsonEncode(): String = - buildJsonObject { - putIfNotNull("version", version.orNull) - putJsonArray("versionsOrdering") { addAllIfNotNull(versionsOrdering.orNull) } - putIfNotNull("olderVersionsDir", olderVersionsDir.orNull?.asFile) - putJsonArray("olderVersions") { - addAll(olderVersions.files) - } - putIfNotNull("renderVersionsNavigationOnAllPages", renderVersionsNavigationOnAllPages.orNull) - }.toString() - - companion object { - const val DOKKA_VERSIONING_PLUGIN_PARAMETERS_NAME = "versioning" - const val DOKKA_VERSIONING_PLUGIN_FQN = "org.jetbrains.dokka.versioning.VersioningPlugin" - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatDependencyContainers.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatDependencyContainers.kt deleted file mode 100644 index ea27b4c9d1..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatDependencyContainers.kt +++ /dev/null @@ -1,158 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.api.NamedDomainObjectProvider -import org.gradle.api.Project -import org.gradle.api.artifacts.Configuration -import org.gradle.api.attributes.AttributeContainer -import org.gradle.api.attributes.Bundling.BUNDLING_ATTRIBUTE -import org.gradle.api.attributes.Bundling.EXTERNAL -import org.gradle.api.attributes.Category.CATEGORY_ATTRIBUTE -import org.gradle.api.attributes.Category.LIBRARY -import org.gradle.api.attributes.LibraryElements.JAR -import org.gradle.api.attributes.LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE -import org.gradle.api.attributes.Usage.JAVA_RUNTIME -import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE -import org.gradle.api.attributes.java.TargetJvmEnvironment.STANDARD_JVM -import org.gradle.api.attributes.java.TargetJvmEnvironment.TARGET_JVM_ENVIRONMENT_ATTRIBUTE -import org.gradle.api.model.ObjectFactory -import org.gradle.kotlin.dsl.named -import org.gradle.kotlin.dsl.newInstance -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKATOO_BASE_ATTRIBUTE -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKATOO_CATEGORY_ATTRIBUTE -import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKA_FORMAT_ATTRIBUTE -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.asConsumer -import org.jetbrains.dokka.dokkatoo.internal.asProvider - -/** - * The Dokka-specific Gradle [Configuration]s used to produce and consume files from external sources - * (example: Maven Central), or between subprojects. - * - * (Be careful of the confusing names: Gradle [Configuration]s are used to transfer files, - * [DokkaConfiguration][org.jetbrains.dokka.DokkaConfiguration] - * is used to configure Dokka behaviour.) - */ -@DokkatooInternalApi -class DokkatooFormatDependencyContainers( - private val formatName: String, - dokkatooConsumer: NamedDomainObjectProvider, - project: Project, -) { - - private val objects: ObjectFactory = project.objects - - private val dependencyContainerNames = DokkatooBasePlugin.DependencyContainerNames(formatName) - - private val dokkatooAttributes: DokkatooConfigurationAttributes = objects.newInstance() - - private fun AttributeContainer.dokkaCategory(category: DokkatooConfigurationAttributes.DokkatooCategoryAttribute) { - attribute(DOKKATOO_BASE_ATTRIBUTE, dokkatooAttributes.dokkatooBaseUsage) - attribute(DOKKA_FORMAT_ATTRIBUTE, objects.named(formatName)) - attribute(DOKKATOO_CATEGORY_ATTRIBUTE, category) - } - - private fun AttributeContainer.jvmJar() { - attribute(USAGE_ATTRIBUTE, objects.named(JAVA_RUNTIME)) - attribute(CATEGORY_ATTRIBUTE, objects.named(LIBRARY)) - attribute(BUNDLING_ATTRIBUTE, objects.named(EXTERNAL)) - attribute(TARGET_JVM_ENVIRONMENT_ATTRIBUTE, objects.named(STANDARD_JVM)) - attribute(LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(JAR)) - } - - // - /** Fetch Dokka Module files from other subprojects */ - val dokkaModuleConsumer: NamedDomainObjectProvider = - project.configurations.register(dependencyContainerNames.dokkatooModuleFilesConsumer) { - description = "Fetch Dokka Module files for $formatName from other subprojects" - asConsumer() - extendsFrom(dokkatooConsumer.get()) - attributes { - dokkaCategory(dokkatooAttributes.dokkaModuleFiles) - } - } - - /** Provide Dokka Module files to other subprojects */ - val dokkaModuleOutgoing: NamedDomainObjectProvider = - project.configurations.register(dependencyContainerNames.dokkatooModuleFilesProvider) { - description = "Provide Dokka Module files for $formatName to other subprojects" - asProvider() - // extend from dokkaConfigurationsConsumer, so Dokka Module Configs propagate api() style - extendsFrom(dokkaModuleConsumer.get()) - attributes { - dokkaCategory(dokkatooAttributes.dokkaModuleFiles) - } - } - // - - // - /** - * Dokka plugins. - * - * Users can add plugins to this dependency. - * - * Should not contain runtime dependencies. - */ - val dokkaPluginsClasspath: NamedDomainObjectProvider = - project.configurations.register(dependencyContainerNames.dokkaPluginsClasspath) { - description = "Dokka Plugins classpath for $formatName" - asConsumer() - attributes { - jvmJar() - dokkaCategory(dokkatooAttributes.dokkaPluginsClasspath) - } - } - - /** - * Dokka Plugins, without transitive dependencies. - * - * It extends [dokkaPluginsClasspath], so do not add dependencies to this configuration - - * the dependencies are computed automatically. - */ - val dokkaPluginsIntransitiveClasspath: NamedDomainObjectProvider = - project.configurations.register(dependencyContainerNames.dokkaPluginsIntransitiveClasspath) { - description = - "Dokka Plugins classpath for $formatName - for internal use. Fetch only the plugins (no transitive dependencies) for use in the Dokka JSON Configuration." - asConsumer() - extendsFrom(dokkaPluginsClasspath.get()) - isTransitive = false - attributes { - jvmJar() - dokkaCategory(dokkatooAttributes.dokkaPluginsClasspath) - } - } - // - - // - /** - * Runtime classpath used to execute Dokka Worker. - * - * This configuration is not exposed to other subprojects. - * - * Extends [dokkaPluginsClasspath]. - * - * @see org.jetbrains.dokka.dokkatoo.workers.DokkaGeneratorWorker - * @see org.jetbrains.dokka.dokkatoo.tasks.DokkatooGenerateTask - */ - val dokkaGeneratorClasspath: NamedDomainObjectProvider = - project.configurations.register(dependencyContainerNames.dokkaGeneratorClasspath) { - description = - "Dokka Generator runtime classpath for $formatName - will be used in Dokka Worker. Should contain all transitive dependencies, plugins (and their transitive dependencies), so Dokka Worker can run." - asConsumer() - - // extend from plugins classpath, so Dokka Worker can run the plugins - extendsFrom(dokkaPluginsClasspath.get()) - - isTransitive = true - attributes { - jvmJar() - dokkaCategory(dokkatooAttributes.dokkaGeneratorClasspath) - } - } - // -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatPlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatPlugin.kt deleted file mode 100644 index 5306df92f0..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatPlugin.kt +++ /dev/null @@ -1,183 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.artifacts.Dependency -import org.gradle.api.artifacts.dsl.DependencyHandler -import org.gradle.api.file.FileSystemOperations -import org.gradle.api.model.ObjectFactory -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.provider.ProviderFactory -import org.gradle.kotlin.dsl.apply -import org.gradle.kotlin.dsl.dependencies -import org.gradle.kotlin.dsl.getByType -import org.gradle.kotlin.dsl.withType -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin -import org.jetbrains.dokka.dokkatoo.DokkatooExtension -import org.jetbrains.dokka.dokkatoo.adapters.DokkatooAndroidAdapter -import org.jetbrains.dokka.dokkatoo.adapters.DokkatooJavaAdapter -import org.jetbrains.dokka.dokkatoo.adapters.DokkatooKotlinAdapter -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import javax.inject.Inject - -/** - * Base Gradle Plugin for setting up a Dokka Publication for a specific format. - * - * [DokkatooBasePlugin] must be applied for this plugin (or any subclass) to have an effect. - * - * Anyone can use this class as a basis for a generating a Dokka Publication in a custom format. - */ -abstract class DokkatooFormatPlugin( - val formatName: String, -) : Plugin { - - @get:Inject - @DokkatooInternalApi - protected abstract val objects: ObjectFactory - - @get:Inject - @DokkatooInternalApi - protected abstract val providers: ProviderFactory - - @get:Inject - @DokkatooInternalApi - protected abstract val files: FileSystemOperations - - - override fun apply(target: Project) { - - // apply DokkatooBasePlugin - target.pluginManager.apply(DokkatooBasePlugin::class) - - // apply the plugin that will autoconfigure Dokkatoo to use the sources of a Kotlin project - target.pluginManager.apply(type = DokkatooKotlinAdapter::class) - target.pluginManager.apply(type = DokkatooJavaAdapter::class) - target.pluginManager.apply(type = DokkatooAndroidAdapter::class) - - target.plugins.withType().configureEach { - val dokkatooExtension = target.extensions.getByType(DokkatooExtension::class) - - val publication = dokkatooExtension.dokkatooPublications.create(formatName) - - val dokkatooConsumer = - target.configurations.named(DokkatooBasePlugin.dependencyContainerNames.dokkatoo) - - val dependencyContainers = DokkatooFormatDependencyContainers( - formatName = formatName, - dokkatooConsumer = dokkatooConsumer, - project = target, - ) - - val dokkatooTasks = DokkatooFormatTasks( - project = target, - publication = publication, - dokkatooExtension = dokkatooExtension, - dependencyContainers = dependencyContainers, - providers = providers, - ) - - dependencyContainers.dokkaModuleOutgoing.configure { - outgoing { - artifact(dokkatooTasks.prepareModuleDescriptor.flatMap { it.dokkaModuleDescriptorJson }) - } - outgoing { - artifact(dokkatooTasks.generateModule.flatMap { it.outputDirectory }) { - type = "directory" - } - } - } - - // TODO DokkaCollect replacement - share raw files without first generating a Dokka Module - //dependencyCollections.dokkaParametersOutgoing.configure { - // outgoing { - // artifact(dokkatooTasks.prepareParametersTask.flatMap { it.dokkaConfigurationJson }) - // } - //} - - val context = DokkatooFormatPluginContext( - project = target, - dokkatooExtension = dokkatooExtension, - dokkatooTasks = dokkatooTasks, - formatName = formatName, - ) - - context.configure() - - if (context.addDefaultDokkaDependencies) { - with(context) { - addDefaultDokkaDependencies() - } - } - } - } - - - /** Format specific configuration - to be implemented by subclasses */ - open fun DokkatooFormatPluginContext.configure() {} - - - @DokkatooInternalApi - class DokkatooFormatPluginContext( - val project: Project, - val dokkatooExtension: DokkatooExtension, - val dokkatooTasks: DokkatooFormatTasks, - formatName: String, - ) { - private val dependencyContainerNames = DokkatooBasePlugin.DependencyContainerNames(formatName) - - var addDefaultDokkaDependencies = true - - /** Create a [Dependency] for a Dokka module */ - fun DependencyHandler.dokka(module: String): Provider = - dokkatooExtension.versions.jetbrainsDokka.map { version -> create("org.jetbrains.dokka:$module:$version") } - - /** Add a dependency to the Dokka plugins classpath */ - fun DependencyHandler.dokkaPlugin(dependency: Provider): Unit = - addProvider(dependencyContainerNames.dokkaPluginsClasspath, dependency) - - /** Add a dependency to the Dokka plugins classpath */ - fun DependencyHandler.dokkaPlugin(dependency: String) { - add(dependencyContainerNames.dokkaPluginsClasspath, dependency) - } - - /** Add a dependency to the Dokka Generator classpath */ - fun DependencyHandler.dokkaGenerator(dependency: Provider) { - addProvider(dependencyContainerNames.dokkaGeneratorClasspath, dependency) - } - - /** Add a dependency to the Dokka Generator classpath */ - fun DependencyHandler.dokkaGenerator(dependency: String) { - add(dependencyContainerNames.dokkaGeneratorClasspath, dependency) - } - } - - - private fun DokkatooFormatPluginContext.addDefaultDokkaDependencies() { - project.dependencies { - /** lazily create a [Dependency] with the provided [version] */ - infix fun String.version(version: Property): Provider = - version.map { v -> create("$this:$v") } - - with(dokkatooExtension.versions) { - dokkaPlugin(dokka("analysis-kotlin-descriptors")) - dokkaPlugin(dokka("templating-plugin")) - dokkaPlugin(dokka("dokka-base")) -// dokkaPlugin(dokka("all-modules-page-plugin")) - - dokkaPlugin("org.jetbrains.kotlinx:kotlinx-html" version kotlinxHtml) - dokkaPlugin("org.freemarker:freemarker" version freemarker) - - dokkaGenerator(dokka("dokka-core")) - // TODO why does org.jetbrains:markdown need a -jvm suffix? - dokkaGenerator("org.jetbrains:markdown-jvm" version jetbrainsMarkdown) - dokkaGenerator("org.jetbrains.kotlinx:kotlinx-coroutines-core" version kotlinxCoroutines) - } - } - } - -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatTasks.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatTasks.kt deleted file mode 100644 index 5b0f227276..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooFormatTasks.kt +++ /dev/null @@ -1,109 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.api.Project -import org.gradle.api.provider.ProviderFactory -import org.gradle.kotlin.dsl.register -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin -import org.jetbrains.dokka.dokkatoo.DokkatooExtension -import org.jetbrains.dokka.dokkatoo.dokka.DokkaPublication -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.LocalProjectOnlyFilter -import org.jetbrains.dokka.dokkatoo.internal.configuring -import org.jetbrains.dokka.dokkatoo.tasks.DokkatooGenerateTask -import org.jetbrains.dokka.dokkatoo.tasks.DokkatooPrepareModuleDescriptorTask - -/** Tasks for generating a Dokkatoo Publication in a specific format. */ -@DokkatooInternalApi -class DokkatooFormatTasks( - project: Project, - private val publication: DokkaPublication, - private val dokkatooExtension: DokkatooExtension, - private val dependencyContainers: DokkatooFormatDependencyContainers, - - private val providers: ProviderFactory, -) { - private val formatName: String get() = publication.formatName - - private val taskNames = DokkatooBasePlugin.TaskNames(formatName) - - private fun DokkatooGenerateTask.applyFormatSpecificConfiguration() { - runtimeClasspath.from( - dependencyContainers.dokkaGeneratorClasspath.map { classpath -> - classpath.incoming.artifacts.artifactFiles - } - ) - generator.apply { - publicationEnabled.convention(publication.enabled) - - failOnWarning.convention(publication.failOnWarning) - finalizeCoroutines.convention(publication.finalizeCoroutines) - includes.from(publication.includes) - moduleName.convention(publication.moduleName) - moduleVersion.convention(publication.moduleVersion) - offlineMode.convention(publication.offlineMode) - pluginsConfiguration.addAllLater(providers.provider { publication.pluginsConfiguration }) - pluginsClasspath.from( - dependencyContainers.dokkaPluginsIntransitiveClasspath.map { classpath -> - classpath.incoming.artifacts.artifactFiles - } - ) - suppressInheritedMembers.convention(publication.suppressInheritedMembers) - suppressObviousFunctions.convention(publication.suppressObviousFunctions) - } - } - - val generatePublication = project.tasks.register( - taskNames.generatePublication, - publication.pluginsConfiguration, - ).configuring task@{ - description = "Executes the Dokka Generator, generating the $formatName publication" - generationType.set(DokkatooGenerateTask.GenerationType.PUBLICATION) - - outputDirectory.convention(dokkatooExtension.dokkatooPublicationDirectory.dir(formatName)) - - generator.apply { - // depend on Dokka Module Descriptors from other subprojects - dokkaModuleFiles.from( - dependencyContainers.dokkaModuleConsumer.map { modules -> - modules.incoming - .artifactView { componentFilter(LocalProjectOnlyFilter) } - .artifacts.artifactFiles - } - ) - } - - applyFormatSpecificConfiguration() - } - - val generateModule = project.tasks.register( - taskNames.generateModule, - publication.pluginsConfiguration, - ).configuring task@{ - description = "Executes the Dokka Generator, generating a $formatName module" - generationType.set(DokkatooGenerateTask.GenerationType.MODULE) - - outputDirectory.convention(dokkatooExtension.dokkatooModuleDirectory.dir(formatName)) - - applyFormatSpecificConfiguration() - } - - val prepareModuleDescriptor = project.tasks.register( - taskNames.prepareModuleDescriptor - ) task@{ - description = "Prepares the Dokka Module Descriptor for $formatName" - includes.from(publication.includes) - dokkaModuleDescriptorJson.convention( - dokkatooExtension.dokkatooConfigurationsDirectory.file("$formatName/module_descriptor.json") - ) - moduleDirectory.set(generateModule.flatMap { it.outputDirectory }) - -// dokkaSourceSets.addAllLater(providers.provider { dokkatooExtension.dokkatooSourceSets }) -// dokkaSourceSets.configureEach { -// sourceSetScope.convention(this@task.path) -// } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooGfmPlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooGfmPlugin.kt deleted file mode 100644 index 9d4cd23a58..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooGfmPlugin.kt +++ /dev/null @@ -1,18 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.kotlin.dsl.dependencies -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi - -abstract class DokkatooGfmPlugin -@DokkatooInternalApi -constructor() : DokkatooFormatPlugin(formatName = "gfm") { - override fun DokkatooFormatPluginContext.configure() { - project.dependencies { - dokkaPlugin(dokka("gfm-plugin")) - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooHtmlPlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooHtmlPlugin.kt deleted file mode 100644 index 84dd3d85f6..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooHtmlPlugin.kt +++ /dev/null @@ -1,78 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.api.tasks.TaskProvider -import org.gradle.kotlin.dsl.register -import org.gradle.kotlin.dsl.registerBinding -import org.gradle.kotlin.dsl.withType -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaHtmlPluginParameters -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaHtmlPluginParameters.Companion.DOKKA_HTML_PARAMETERS_NAME -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaVersioningPluginParameters -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaVersioningPluginParameters.Companion.DOKKA_VERSIONING_PLUGIN_PARAMETERS_NAME -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.uppercaseFirstChar -import org.jetbrains.dokka.dokkatoo.tasks.LogHtmlPublicationLinkTask - -abstract class DokkatooHtmlPlugin -@DokkatooInternalApi -constructor() : DokkatooFormatPlugin(formatName = "html") { - - override fun DokkatooFormatPluginContext.configure() { - registerDokkaBasePluginConfiguration() - registerDokkaVersioningPlugin() - - val logHtmlUrlTask = registerLogHtmlUrlTask() - - dokkatooTasks.generatePublication.configure { - finalizedBy(logHtmlUrlTask) - } - } - - private fun DokkatooFormatPluginContext.registerDokkaBasePluginConfiguration() { - with(dokkatooExtension.pluginsConfiguration) { - registerBinding(DokkaHtmlPluginParameters::class, DokkaHtmlPluginParameters::class) - register(DOKKA_HTML_PARAMETERS_NAME) - withType().configureEach { - separateInheritedMembers.convention(false) - mergeImplicitExpectActualDeclarations.convention(false) - } - } - } - - private fun DokkatooFormatPluginContext.registerDokkaVersioningPlugin() { - // register and configure Dokka Versioning Plugin - with(dokkatooExtension.pluginsConfiguration) { - registerBinding( - DokkaVersioningPluginParameters::class, - DokkaVersioningPluginParameters::class, - ) - register(DOKKA_VERSIONING_PLUGIN_PARAMETERS_NAME) - withType().configureEach { - renderVersionsNavigationOnAllPages.convention(true) - } - } - } - - private fun DokkatooFormatPluginContext.registerLogHtmlUrlTask(): - TaskProvider { - - val indexHtmlFile = dokkatooTasks.generatePublication - .flatMap { it.outputDirectory.file("index.html") } - - val indexHtmlPath = indexHtmlFile.map { indexHtml -> - indexHtml.asFile - .relativeTo(project.rootDir.parentFile) - .invariantSeparatorsPath - } - - return project.tasks.register( - "logLink" + dokkatooTasks.generatePublication.name.uppercaseFirstChar() - ) { - serverUri.convention("http://localhost:63342") - this.indexHtmlPath.convention(indexHtmlPath) - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooJavadocPlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooJavadocPlugin.kt deleted file mode 100644 index e3730f46d7..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooJavadocPlugin.kt +++ /dev/null @@ -1,18 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.kotlin.dsl.dependencies -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi - -abstract class DokkatooJavadocPlugin -@DokkatooInternalApi -constructor() : DokkatooFormatPlugin(formatName = "javadoc") { - override fun DokkatooFormatPluginContext.configure() { - project.dependencies { - dokkaPlugin(dokka("javadoc-plugin")) - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooJekyllPlugin.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooJekyllPlugin.kt deleted file mode 100644 index c912816fdb..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/formats/DokkatooJekyllPlugin.kt +++ /dev/null @@ -1,18 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.formats - -import org.gradle.kotlin.dsl.dependencies -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi - -abstract class DokkatooJekyllPlugin -@DokkatooInternalApi -constructor() : DokkatooFormatPlugin(formatName = "jekyll") { - override fun DokkatooFormatPluginContext.configure() { - project.dependencies { - dokkaPlugin(dokka("jekyll-plugin")) - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/DokkatooInternalApi.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/DokkatooInternalApi.kt deleted file mode 100644 index 6a4a7e2f5f..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/DokkatooInternalApi.kt +++ /dev/null @@ -1,41 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import kotlin.RequiresOptIn.Level.WARNING -import kotlin.annotation.AnnotationRetention.BINARY -import kotlin.annotation.AnnotationTarget.* - - -/** - * Functionality that is annotated with this API is intended only for use by Dokkatoo internal code, - * but it has been given - * [`public` visibility](https://kotlinlang.org/docs/visibility-modifiers.html) - * for technical reasons. - * - * Any code that is annotated with this may be used - * - * Anyone is welcome to - * [opt in](https://kotlinlang.org/docs/opt-in-requirements.html#opt-in-to-using-api) - * to use this API, but be aware that it might change unexpectedly and without warning or migration - * hints. - * - * If you find yourself needing to opt in, then please report your use-case on - * [the Dokkatoo issue tracker](https://github.com/adamko-dev/dokkatoo/issues). - */ -@RequiresOptIn( - "Internal API - may change at any time without notice", - level = WARNING -) -@Retention(BINARY) -@Target( - CLASS, - FUNCTION, - CONSTRUCTOR, - PROPERTY, - PROPERTY_GETTER, -) -@MustBeDocumented -annotation class DokkatooInternalApi diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/LoggerAdapter.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/LoggerAdapter.kt deleted file mode 100644 index ba6e71b16e..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/LoggerAdapter.kt +++ /dev/null @@ -1,69 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import org.jetbrains.dokka.utilities.DokkaLogger -import org.jetbrains.dokka.utilities.LoggingLevel -import java.io.File -import java.io.Writer -import java.util.concurrent.atomic.AtomicInteger - -/** - * Logs all Dokka messages to a file. - * - * @see org.jetbrains.dokka.DokkaGenerator - */ -// Gradle causes OOM errors when there is a lot of console output. Logging to file is a workaround. -// https://github.com/gradle/gradle/issues/23965 -// https://github.com/gradle/gradle/issues/15621 -internal class LoggerAdapter( - outputFile: File -) : DokkaLogger, AutoCloseable { - - private val logWriter: Writer - - init { - if (!outputFile.exists()) { - outputFile.parentFile.mkdirs() - outputFile.createNewFile() - } - - logWriter = outputFile.bufferedWriter() - } - - private val warningsCounter = AtomicInteger() - private val errorsCounter = AtomicInteger() - - override var warningsCount: Int - get() = warningsCounter.get() - set(value) = warningsCounter.set(value) - - override var errorsCount: Int - get() = errorsCounter.get() - set(value) = errorsCounter.set(value) - - override fun debug(message: String) = log(LoggingLevel.DEBUG, message) - override fun progress(message: String) = log(LoggingLevel.PROGRESS, message) - override fun info(message: String) = log(LoggingLevel.INFO, message) - - override fun warn(message: String) { - warningsCount++ - log(LoggingLevel.WARN, message) - } - - override fun error(message: String) { - errorsCount++ - log(LoggingLevel.ERROR, message) - } - - @Synchronized - private fun log(level: LoggingLevel, message: String) { - logWriter.appendLine("[${level.name}] $message") - } - - override fun close() { - logWriter.close() - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/collectionsUtils.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/collectionsUtils.kt deleted file mode 100644 index 5cccfce1a1..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/collectionsUtils.kt +++ /dev/null @@ -1,11 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -internal fun Set.mapToSet(transform: (T) -> R): Set = - mapTo(mutableSetOf(), transform) - -internal fun Set.mapNotNullToSet(transform: (T) -> R?): Set = - mapNotNullTo(mutableSetOf(), transform) diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleExtensionAccessors.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleExtensionAccessors.kt deleted file mode 100644 index dbab1db3d4..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleExtensionAccessors.kt +++ /dev/null @@ -1,13 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import org.jetbrains.dokka.dokkatoo.DokkatooExtension - -// When Dokkatoo is applied to a build script Gradle will auto-generate these accessors - -internal fun DokkatooExtension.versions(configure: DokkatooExtension.Versions.() -> Unit) { - versions.apply(configure) -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleTypealiases.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleTypealiases.kt deleted file mode 100644 index a4cd28f05f..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleTypealiases.kt +++ /dev/null @@ -1,24 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import org.gradle.api.ExtensiblePolymorphicDomainObjectContainer -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaPluginParametersBaseSpec - -/** Container for all [Dokka Plugin parameters][DokkaPluginParametersBaseSpec]. */ -typealias DokkaPluginParametersContainer = - ExtensiblePolymorphicDomainObjectContainer - - -/** - * The path of a Gradle [Project][org.gradle.api.Project]. This is unique per subproject. - * This is _not_ the file path, which - * [can be configured to be different to the project path](https://docs.gradle.org/current/userguide/fine_tuning_project_layout.html#sub:modifying_element_of_the_project_tree). - * - * Example: `:modules:tests:alpha-project`. - * - * @see org.gradle.api.Project.getPath - */ -internal typealias GradleProjectPath = org.gradle.util.Path diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleUtils.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleUtils.kt deleted file mode 100644 index 52dd089e3c..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/gradleUtils.kt +++ /dev/null @@ -1,193 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import org.gradle.api.* -import org.gradle.api.artifacts.ArtifactView -import org.gradle.api.artifacts.Configuration -import org.gradle.api.artifacts.ConfigurationContainer -import org.gradle.api.artifacts.component.ComponentIdentifier -import org.gradle.api.artifacts.component.ProjectComponentIdentifier -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.model.ObjectFactory -import org.gradle.api.plugins.ExtensionAware -import org.gradle.api.plugins.ExtensionContainer -import org.gradle.api.provider.Provider -import org.gradle.api.specs.Spec -import org.gradle.api.tasks.TaskProvider -import org.gradle.kotlin.dsl.add -import org.gradle.kotlin.dsl.domainObjectContainer -import org.gradle.kotlin.dsl.polymorphicDomainObjectContainer -import org.jetbrains.dokka.dokkatoo.dokka.plugins.DokkaPluginParametersBaseSpec - - -/** - * Mark this [Configuration] as one that will be consumed by other subprojects. - * - * ``` - * isCanBeResolved = false - * isCanBeConsumed = true - * ``` - */ -internal fun Configuration.asProvider( - visible: Boolean = true, -) { - isCanBeResolved = false - isCanBeConsumed = true - isVisible = visible -} - -/** - * Mark this [Configuration] as one that will consume artifacts from other subprojects (also known as 'resolving') - * - * ``` - * isCanBeResolved = true - * isCanBeConsumed = false - * ``` - * */ -internal fun Configuration.asConsumer( - visible: Boolean = false, -) { - isCanBeResolved = true - isCanBeConsumed = false - isVisible = visible -} - - -/** Invert a boolean [Provider] */ -internal operator fun Provider.not(): Provider = map { !it } - - -/** Only matches components that come from subprojects */ -internal object LocalProjectOnlyFilter : Spec { - override fun isSatisfiedBy(element: ComponentIdentifier?): Boolean = - element is ProjectComponentIdentifier -} - - -/** Invert the result of a [Spec] predicate */ -internal operator fun Spec.not(): Spec = Spec { !this@not.isSatisfiedBy(it) } - - -internal fun Project.pathAsFilePath() = path - .removePrefix(GradleProjectPath.SEPARATOR) - .replace(GradleProjectPath.SEPARATOR, "/") - - -/** - * Apply some configuration to a [Task] using - * [configure][org.gradle.api.tasks.TaskContainer.configure], - * and return the same [TaskProvider]. - */ -internal fun TaskProvider.configuring( - block: Action -): TaskProvider = apply { configure(block) } - - -internal fun NamedDomainObjectContainer.maybeCreate( - name: String, - configure: T.() -> Unit, -): T = maybeCreate(name).apply(configure) - - -/** - * Aggregate the incoming files from a [Configuration] (with name [named]) into [collector]. - * - * Configurations that do not exist or cannot be - * [resolved][org.gradle.api.artifacts.Configuration.isCanBeResolved] - * will be ignored. - * - * @param[builtBy] An optional [TaskProvider], used to set [ConfigurableFileCollection.builtBy]. - * This should not typically be used, and is only necessary in rare cases where a Gradle Plugin is - * misconfigured. - */ -internal fun ConfigurationContainer.collectIncomingFiles( - named: String, - collector: ConfigurableFileCollection, - builtBy: TaskProvider<*>? = null, - artifactViewConfiguration: ArtifactView.ViewConfiguration.() -> Unit = { - // ignore failures: it's usually okay if fetching files is best-effort because - // maybe Dokka doesn't need _all_ dependencies - lenient(true) - }, -) { - val conf = findByName(named) - if (conf != null && conf.isCanBeResolved) { - val incomingFiles = conf.incoming - .artifactView(artifactViewConfiguration) - .artifacts - .resolvedArtifacts // using 'resolved' might help with triggering artifact transforms? - .map { artifacts -> artifacts.map { it.file } } - - collector.from(incomingFiles) - - if (builtBy != null) { - collector.builtBy(builtBy) - } - } -} - - -/** - * Create a new [NamedDomainObjectContainer], using - * [org.gradle.kotlin.dsl.domainObjectContainer] - * (but [T] is `reified`). - * - * @param[factory] an optional factory for creating elements - * @see org.gradle.kotlin.dsl.domainObjectContainer - */ -internal inline fun ObjectFactory.domainObjectContainer( - factory: NamedDomainObjectFactory? = null -): NamedDomainObjectContainer = - if (factory == null) { - domainObjectContainer(T::class) - } else { - domainObjectContainer(T::class, factory) - } - - -/** - * Create a new [ExtensiblePolymorphicDomainObjectContainer], using - * [org.gradle.kotlin.dsl.polymorphicDomainObjectContainer] - * (but [T] is `reified`). - * - * @see org.gradle.kotlin.dsl.polymorphicDomainObjectContainer - */ -internal inline fun ObjectFactory.polymorphicDomainObjectContainer() - : ExtensiblePolymorphicDomainObjectContainer = - polymorphicDomainObjectContainer(T::class) - - -/** - * Add an extension to the [ExtensionContainer], and return the value. - * - * Adding an extension is especially useful for improving the DSL in build scripts when [T] is a - * [NamedDomainObjectContainer]. - * Using an extension will allow Gradle to generate - * [type-safe model accessors](https://docs.gradle.org/current/userguide/kotlin_dsl.html#kotdsl:accessor_applicability) - * for added types. - * - * ([name] should match the property name. This has to be done manually. I tried using a - * delegated-property provider but then Gradle can't introspect the types properly, so it fails to - * create accessors). - */ -internal inline fun ExtensionContainer.adding( - name: String, - value: T, -): T { - add(name, value) - return value -} - - -/** Create a new [DokkaPluginParametersContainer] instance. */ -internal fun ObjectFactory.dokkaPluginParametersContainer(): DokkaPluginParametersContainer { - val container = polymorphicDomainObjectContainer() - container.whenObjectAdded { - // workaround for https://github.com/gradle/gradle/issues/24972 - (container as ExtensionAware).extensions.add(name, this) - } - return container -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/kotlinxSerializationUtils.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/kotlinxSerializationUtils.kt deleted file mode 100644 index cf0f369fd2..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/kotlinxSerializationUtils.kt +++ /dev/null @@ -1,40 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import kotlinx.serialization.json.JsonArrayBuilder -import kotlinx.serialization.json.JsonObjectBuilder -import kotlinx.serialization.json.JsonPrimitive -import kotlinx.serialization.json.add -import java.io.File - - -@JvmName("addAllFiles") -internal fun JsonArrayBuilder.addAll(files: Iterable) { - files - .map { it.canonicalFile.invariantSeparatorsPath } - .forEach { path -> add(path) } -} - -@JvmName("addAllStrings") -internal fun JsonArrayBuilder.addAll(values: Iterable) { - values.forEach { add(it) } -} - -internal fun JsonArrayBuilder.addAllIfNotNull(values: Iterable?) { - if (values != null) addAll(values) -} - -internal fun JsonObjectBuilder.putIfNotNull(key: String, value: Boolean?) { - if (value != null) put(key, JsonPrimitive(value)) -} - -internal fun JsonObjectBuilder.putIfNotNull(key: String, value: String?) { - if (value != null) put(key, JsonPrimitive(value)) -} - -internal fun JsonObjectBuilder.putIfNotNull(key: String, value: File?) { - if (value != null) put(key, JsonPrimitive(value.canonicalFile.invariantSeparatorsPath)) -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/stringUtils.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/stringUtils.kt deleted file mode 100644 index 2ac580b006..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/stringUtils.kt +++ /dev/null @@ -1,15 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - - -/** - * Title case the first char of a string. - * - * (Custom implementation because [uppercase] is deprecated, and Dokkatoo should try and be as - * stable as possible.) - */ -internal fun String.uppercaseFirstChar(): String = - if (isNotEmpty()) Character.toTitleCase(this[0]) + substring(1) else this diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/uriUtils.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/uriUtils.kt deleted file mode 100644 index ad839a475c..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/internal/uriUtils.kt +++ /dev/null @@ -1,13 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.internal - -import java.net.URI - -internal fun URI.appendPath(addition: String): URI { - val currentPath = path.removeSuffix("/") - val newPath = "$currentPath/$addition" - return resolve(newPath).normalize() -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooGenerateTask.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooGenerateTask.kt deleted file mode 100644 index 0155e12736..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooGenerateTask.kt +++ /dev/null @@ -1,195 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.tasks - -import kotlinx.serialization.json.JsonElement -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.model.ObjectFactory -import org.gradle.api.provider.ListProperty -import org.gradle.api.provider.Property -import org.gradle.api.tasks.* -import org.gradle.kotlin.dsl.newInstance -import org.gradle.kotlin.dsl.submit -import org.gradle.process.JavaForkOptions -import org.gradle.workers.WorkerExecutor -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin.Companion.jsonMapper -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaGeneratorParametersSpec -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaModuleDescriptionKxs -import org.jetbrains.dokka.dokkatoo.dokka.parameters.builders.DokkaParametersBuilder -import org.jetbrains.dokka.dokkatoo.internal.DokkaPluginParametersContainer -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.workers.DokkaGeneratorWorker -import org.jetbrains.dokka.toPrettyJsonString -import java.io.IOException -import javax.inject.Inject - -/** - * Executes the Dokka Generator, and produces documentation. - * - * The type of documentation generated is determined by the supplied Dokka Plugins in [generator]. - */ -@CacheableTask -abstract class DokkatooGenerateTask -@DokkatooInternalApi -@Inject -constructor( - objects: ObjectFactory, - private val workers: WorkerExecutor, - - /** - * Configurations for Dokka Generator Plugins. Must be provided from - * [org.jetbrains.dokka.dokkatoo.dokka.DokkaPublication.pluginsConfiguration]. - */ - pluginsConfiguration: DokkaPluginParametersContainer, -) : DokkatooTask() { - - @get:OutputDirectory - abstract val outputDirectory: DirectoryProperty - - /** - * Classpath required to run Dokka Generator. - * - * Contains the Dokka Generator, Dokka plugins, and any transitive dependencies. - */ - @get:Classpath - abstract val runtimeClasspath: ConfigurableFileCollection - - @get:LocalState - abstract val cacheDirectory: DirectoryProperty - - /** - * Generating a Dokka Module? Set this to [GenerationType.MODULE]. - * - * Generating a Dokka Publication? [GenerationType.PUBLICATION]. - */ - @get:Input - abstract val generationType: Property - - /** @see org.jetbrains.dokka.dokkatoo.dokka.DokkaPublication.enabled */ - @get:Input - abstract val publicationEnabled: Property - - @get:Nested - val generator: DokkaGeneratorParametersSpec = objects.newInstance(pluginsConfiguration) - - /** @see JavaForkOptions.getDebug */ - @get:Input - abstract val workerDebugEnabled: Property - - /** @see JavaForkOptions.getMinHeapSize */ - @get:Input - @get:Optional - abstract val workerMinHeapSize: Property - - /** @see JavaForkOptions.getMaxHeapSize */ - @get:Input - @get:Optional - abstract val workerMaxHeapSize: Property - - /** @see JavaForkOptions.jvmArgs */ - @get:Input - abstract val workerJvmArgs: ListProperty - - @get:Internal - abstract val workerLogFile: RegularFileProperty - - /** - * The [DokkaConfiguration] by Dokka Generator can be saved to a file for debugging purposes. - * To disable this behaviour set this property to `null`. - */ - @DokkatooInternalApi - @get:Internal - abstract val dokkaConfigurationJsonFile: RegularFileProperty - - enum class GenerationType { - MODULE, - PUBLICATION, - } - - @TaskAction - internal fun generateDocumentation() { - val dokkaConfiguration = createDokkaConfiguration() - logger.info("dokkaConfiguration: $dokkaConfiguration") - dumpDokkaConfigurationJson(dokkaConfiguration) - - logger.info("DokkaGeneratorWorker runtimeClasspath: ${runtimeClasspath.asPath}") - - val workQueue = workers.processIsolation { - classpath.from(runtimeClasspath) - forkOptions { - defaultCharacterEncoding = "UTF-8" - minHeapSize = workerMinHeapSize.orNull - maxHeapSize = workerMaxHeapSize.orNull - enableAssertions = true - debug = workerDebugEnabled.get() - jvmArgs = workerJvmArgs.get() - } - } - - workQueue.submit(DokkaGeneratorWorker::class) { - this.dokkaParameters.set(dokkaConfiguration) - this.logFile.set(workerLogFile) - } - } - - /** - * Dump the [DokkaConfiguration] JSON to a file ([dokkaConfigurationJsonFile]) for debugging - * purposes. - */ - private fun dumpDokkaConfigurationJson( - dokkaConfiguration: DokkaConfiguration, - ) { - val destFile = dokkaConfigurationJsonFile.asFile.orNull ?: return - destFile.parentFile.mkdirs() - destFile.createNewFile() - - val compactJson = dokkaConfiguration.toPrettyJsonString() - val json = jsonMapper.decodeFromString(JsonElement.serializer(), compactJson) - val prettyJson = jsonMapper.encodeToString(JsonElement.serializer(), json) - - destFile.writeText(prettyJson) - - logger.info("[$path] Dokka Generator configuration JSON: ${destFile.toURI()}") - } - - private fun createDokkaConfiguration(): DokkaConfiguration { - val outputDirectory = outputDirectory.get().asFile - - val delayTemplateSubstitution = when (generationType.orNull) { - GenerationType.MODULE -> true - GenerationType.PUBLICATION -> false - null -> error("missing GenerationType") - } - - val dokkaModuleDescriptors = dokkaModuleDescriptors() - - return DokkaParametersBuilder.build( - spec = generator, - delayTemplateSubstitution = delayTemplateSubstitution, - outputDirectory = outputDirectory, - modules = dokkaModuleDescriptors, - cacheDirectory = cacheDirectory.asFile.orNull, - ) - } - - private fun dokkaModuleDescriptors(): List { - return generator.dokkaModuleFiles.asFileTree - .matching { include("**/module_descriptor.json") } - .files.map { file -> - try { - val fileContent = file.readText() - jsonMapper.decodeFromString( - DokkaModuleDescriptionKxs.serializer(), - fileContent, - ) - } catch (ex: Exception) { - throw IOException("Could not parse DokkaModuleDescriptionKxs from $file", ex) - } - } - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooPrepareModuleDescriptorTask.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooPrepareModuleDescriptorTask.kt deleted file mode 100644 index 5bce55357b..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooPrepareModuleDescriptorTask.kt +++ /dev/null @@ -1,68 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.tasks - -import kotlinx.serialization.encodeToString -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.provider.Property -import org.gradle.api.tasks.* -import org.gradle.api.tasks.PathSensitivity.RELATIVE -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin.Companion.jsonMapper -import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaModuleDescriptionKxs -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import javax.inject.Inject - -/** - * Produces a Dokka Configuration that describes a single module of a multimodule Dokka configuration. - * - * @see org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaModuleDescriptionKxs - */ -@CacheableTask -abstract class DokkatooPrepareModuleDescriptorTask -@DokkatooInternalApi -@Inject -constructor() : DokkatooTask() { - - @get:OutputFile - abstract val dokkaModuleDescriptorJson: RegularFileProperty - - @get:Input - abstract val moduleName: Property - - @get:Input - abstract val modulePath: Property - - @get:InputDirectory - @get:PathSensitive(RELATIVE) - abstract val moduleDirectory: DirectoryProperty - - @get:InputFiles - @get:Optional - @get:PathSensitive(RELATIVE) - abstract val includes: ConfigurableFileCollection - - @TaskAction - internal fun generateModuleConfiguration() { - val moduleName = moduleName.get() - val moduleDirectory = moduleDirectory.asFile.get() - val includes = includes.files - val modulePath = modulePath.get() - - val moduleDesc = DokkaModuleDescriptionKxs( - name = moduleName, - sourceOutputDirectory = moduleDirectory, - includes = includes, - modulePath = modulePath, - ) - - val encodedModuleDesc = jsonMapper.encodeToString(moduleDesc) - - logger.info("encodedModuleDesc: $encodedModuleDesc") - - dokkaModuleDescriptorJson.get().asFile.writeText(encodedModuleDesc) - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooTask.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooTask.kt deleted file mode 100644 index eb919201f8..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/DokkatooTask.kt +++ /dev/null @@ -1,26 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.tasks - -import org.gradle.api.DefaultTask -import org.gradle.api.model.ObjectFactory -import org.gradle.api.tasks.CacheableTask -import org.jetbrains.dokka.dokkatoo.DokkatooBasePlugin -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import javax.inject.Inject - -/** Base Dokkatoo task */ -@CacheableTask -abstract class DokkatooTask -@DokkatooInternalApi -constructor() : DefaultTask() { - - @get:Inject - abstract val objects: ObjectFactory - - init { - group = DokkatooBasePlugin.TASK_GROUP - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/LogHtmlPublicationLinkTask.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/LogHtmlPublicationLinkTask.kt deleted file mode 100644 index 7576da38fc..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/tasks/LogHtmlPublicationLinkTask.kt +++ /dev/null @@ -1,160 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.tasks - -import org.gradle.api.provider.Property -import org.gradle.api.provider.ProviderFactory -import org.gradle.api.provider.ValueSource -import org.gradle.api.provider.ValueSourceParameters -import org.gradle.api.tasks.Console -import org.gradle.api.tasks.TaskAction -import org.gradle.kotlin.dsl.of -import org.gradle.work.DisableCachingByDefault -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.appendPath -import org.jetbrains.dokka.dokkatoo.tasks.LogHtmlPublicationLinkTask.Companion.ENABLE_TASK_PROPERTY_NAME -import java.net.URI -import java.net.http.HttpClient -import java.net.http.HttpRequest -import java.net.http.HttpResponse -import java.time.Duration -import javax.inject.Inject - -/** - * Prints an HTTP link in the console when the HTML publication is generated. - * - * The HTML publication requires a web server, since it loads resources via javascript. - * - * By default, it uses - * [IntelliJ's built-in server](https://www.jetbrains.com/help/idea/php-built-in-web-server.html) - * to host the file. - * - * This task can be disabled using the [ENABLE_TASK_PROPERTY_NAME] project property. - */ -@DisableCachingByDefault(because = "logging-only task") -abstract class LogHtmlPublicationLinkTask -@Inject -@DokkatooInternalApi -constructor( - providers: ProviderFactory -) : DokkatooTask() { - - @get:Console - abstract val serverUri: Property - - /** - * Path to the `index.html` of the publication. Will be appended to [serverUri]. - * - * The IntelliJ built-in server requires a relative path originating from the _parent_ directory - * of the IntelliJ project. - * - * For example, - * - * * given an IntelliJ project path of - * ``` - * /Users/rachel/projects/my-project/ - * ``` - * * and the publication is generated with an index file - * ``` - * /Users/rachel/projects/my-project/docs/build/dokka/html/index.html - * ```` - * * then IntelliJ requires the [indexHtmlPath] is - * ``` - * my-project/docs/build/dokka/html/index.html - * ``` - * * so that (assuming [serverUri] is `http://localhost:63342`) the logged URL is - * ``` - * http://localhost:63342/my-project/docs/build/dokka/html/index.html - * ``` - */ - @get:Console - abstract val indexHtmlPath: Property - - init { - // don't assign a group. This task is a 'finalizer' util task, so it doesn't make sense - // to display this task prominently. - group = "other" - - val serverActive = providers.of(ServerActiveCheck::class) { - parameters.uri.convention(serverUri) - } - super.onlyIf("server URL is reachable") { serverActive.get() } - - val logHtmlPublicationLinkTaskEnabled = providers - .gradleProperty(ENABLE_TASK_PROPERTY_NAME) - .orElse("true") - .map(String::toBoolean) - super.onlyIf("task is enabled via property") { - logHtmlPublicationLinkTaskEnabled.get() - } - } - - @TaskAction - fun exec() { - val serverUri = serverUri.orNull - val filePath = indexHtmlPath.orNull - - if (serverUri != null && !filePath.isNullOrBlank()) { - val link = URI(serverUri).appendPath(filePath).toString() - - logger.lifecycle("Generated Dokka HTML publication: $link") - } - } - - /** - * Check if the server URI that can host the generated Dokka HTML publication is accessible. - * - * Use the [HttpClient] included with Java 11 to avoid bringing in a new dependency for such - * a small util. - * - * The check uses a [ValueSource] source to attempt to be compatible with Configuration Cache, but - * I'm not certain that this is necessary, or if a [ValueSource] is the best way to achieve it. - */ - internal abstract class ServerActiveCheck : ValueSource { - - interface Parameters : ValueSourceParameters { - /** E.g. `http://localhost:63342` */ - val uri: Property - } - - override fun obtain(): Boolean { - try { - val uri = URI.create(parameters.uri.get()) - val client = HttpClient.newHttpClient() - val request = HttpRequest - .newBuilder() - .uri(uri) - .timeout(Duration.ofSeconds(1)) - .GET() - .build() - val response = client.send(request, HttpResponse.BodyHandlers.ofString()) - - // don't care about the status - only if the server is available - return response.statusCode() > 0 - } catch (ex: Exception) { - return false - } - } - } - - companion object { - /** - * Control whether the [LogHtmlPublicationLinkTask] task is enabled. Useful for disabling the - * task locally, or in CI/CD, or for tests. - * - * ```properties - * #$GRADLE_USER_HOME/gradle.properties - * org.jetbrains.dokka.dokkatoo.tasks.logHtmlPublicationLinkEnabled=false - * ``` - * - * or via an environment variable - * - * ```env - * ORG_GRADLE_PROJECT_org.jetbrains.dokka.dokkatoo.tasks.logHtmlPublicationLinkEnabled=false - * ``` - */ - const val ENABLE_TASK_PROPERTY_NAME = "org.jetbrains.dokka.dokkatoo.tasks.logHtmlPublicationLinkEnabled" - } -} diff --git a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/workers/DokkaGeneratorWorker.kt b/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/workers/DokkaGeneratorWorker.kt deleted file mode 100644 index 34c1c70ecb..0000000000 --- a/dokka-runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/dokkatoo/workers/DokkaGeneratorWorker.kt +++ /dev/null @@ -1,81 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package org.jetbrains.dokka.dokkatoo.workers - -import org.gradle.api.file.RegularFileProperty -import org.gradle.api.provider.Property -import org.gradle.workers.WorkAction -import org.gradle.workers.WorkParameters -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.DokkaGenerator -import org.jetbrains.dokka.dokkatoo.internal.DokkatooInternalApi -import org.jetbrains.dokka.dokkatoo.internal.LoggerAdapter -import java.io.File -import java.time.Duration - -/** - * Gradle Worker Daemon for running [DokkaGenerator]. - * - * The worker requires [DokkaGenerator] is present on its classpath, as well as any Dokka plugins - * that are used to generate the Dokka files. Transitive dependencies are also required. - */ -@DokkatooInternalApi -abstract class DokkaGeneratorWorker : WorkAction { - - @DokkatooInternalApi - interface Parameters : WorkParameters { - val dokkaParameters: Property - val logFile: RegularFileProperty - } - - override fun execute() { - val dokkaParameters = parameters.dokkaParameters.get() - - prepareOutputDir(dokkaParameters) - - executeDokkaGenerator( - parameters.logFile.get().asFile, - dokkaParameters, - ) - } - - private fun prepareOutputDir(dokkaParameters: DokkaConfiguration) { - // Dokka Generator doesn't clean up old files, so we need to manually clean the output directory - dokkaParameters.outputDir.deleteRecursively() - dokkaParameters.outputDir.mkdirs() - - // workaround until https://github.com/Kotlin/dokka/pull/2867 is released - dokkaParameters.modules.forEach { module -> - val moduleDir = dokkaParameters.outputDir.resolve(module.relativePathToOutputDirectory) - moduleDir.mkdirs() - } - } - - private fun executeDokkaGenerator( - logFile: File, - dokkaParameters: DokkaConfiguration - ) { - LoggerAdapter(logFile).use { logger -> - logger.progress("Executing DokkaGeneratorWorker with dokkaParameters: $dokkaParameters") - - val generator = DokkaGenerator(dokkaParameters, logger) - - val duration = measureTime { generator.generate() } - - logger.info("DokkaGeneratorWorker completed in $duration") - } - } - - @DokkatooInternalApi - companion object { - // can't use kotlin.Duration or kotlin.time.measureTime {} because - // the implementation isn't stable across Kotlin versions - private fun measureTime(block: () -> Unit): Duration = - System.nanoTime().let { startTime -> - block() - Duration.ofNanos(System.nanoTime() - startTime) - } - } -}