From 8e5c63d035ef44a269b8c43430f43f5c8eebfb63 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Fri, 10 Nov 2023 11:46:54 +0100 Subject: Restructure the project to utilize included builds (#3174) * Refactor and simplify artifact publishing * Update Gradle to 8.4 * Refactor and simplify convention plugins and build scripts Fixes #3132 --------- Co-authored-by: Adam <897017+aSemy@users.noreply.github.com> Co-authored-by: Oleg Yukhnevich --- .../org/jetbrains/dokka/gradle/DokkaArtifacts.kt | 29 -- .../dokka/gradle/DokkaMultiModuleFileLayout.kt | 94 ---- .../org/jetbrains/dokka/gradle/DokkaPlugin.kt | 131 ------ .../org/jetbrains/dokka/gradle/DokkaProperty.kt | 10 - .../jetbrains/dokka/gradle/DokkaSourceSetMapper.kt | 76 ---- .../dokka/gradle/GradleDokkaSourceSetBuilder.kt | 483 --------------------- .../GradleDokkaSourceSetBuilderExtensions.kt | 36 -- .../gradle/GradleDokkaSourceSetBuilderFactory.kt | 12 - .../GradleExternalDocumentationLinkBuilder.kt | 80 ---- .../dokka/gradle/GradlePackageOptionsBuilder.kt | 113 ----- .../dokka/gradle/GradleSourceLinkBuilder.kt | 102 ----- .../gradle/TaskDependencyInternalWithAdditions.kt | 22 - .../jetbrains/dokka/gradle/automagicTypedProxy.kt | 49 --- .../dokka/gradle/checkChildDokkaTasksIsNotEmpty.kt | 47 -- .../dokka/gradle/checkDependentSourceSets.kt | 28 -- .../dokka/gradle/dokkaBootstrapFactory.kt | 22 - .../dokka/gradle/dokkaDefaultOutputDirectory.kt | 17 - .../dokka/gradle/dokkaSourceSetIDFactory.kt | 18 - .../jetbrains/dokka/gradle/gradleConfigurations.kt | 53 --- .../gradle/internal/AbstractDokkaTaskExtensions.kt | 28 -- .../gradle/kotlin/KotlinGradlePluginVersion.kt | 34 -- .../kotlin/KotlinNativeDistributionAccessor.kt | 39 -- .../dokka/gradle/kotlin/KotlinSourceSetGist.kt | 33 -- .../dokka/gradle/kotlin/isMainSourceSet.kt | 32 -- .../dokka/gradle/kotlin/kotlinClasspathUtils.kt | 109 ----- .../dokka/gradle/kotlin/kotlinCompilationUtils.kt | 81 ---- .../dokka/gradle/kotlin/kotlinSourceSetUtils.kt | 17 - .../dokka/gradle/kotlin/platformOfSourceSet.kt | 17 - .../gradle/sourceSetKotlinGistConfiguration.kt | 32 -- .../dokka/gradle/tasks/AbstractDokkaLeafTask.kt | 41 -- .../dokka/gradle/tasks/AbstractDokkaParentTask.kt | 107 ----- .../dokka/gradle/tasks/AbstractDokkaTask.kt | 257 ----------- .../dokka/gradle/tasks/DokkaCollectorTask.kt | 41 -- .../dokka/gradle/tasks/DokkaMultiModuleTask.kt | 115 ----- .../org/jetbrains/dokka/gradle/tasks/DokkaTask.kt | 29 -- .../dokka/gradle/tasks/DokkaTaskPartial.kt | 32 -- .../kotlin/org/jetbrains/dokka/gradle/utils.kt | 49 --- .../gradle-plugins/org.jetbrains.dokka.properties | 6 - 38 files changed, 2521 deletions(-) delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaArtifacts.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaProperty.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderFactory.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/TaskDependencyInternalWithAdditions.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/automagicTypedProxy.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkChildDokkaTasksIsNotEmpty.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkDependentSourceSets.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaBootstrapFactory.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaDefaultOutputDirectory.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaSourceSetIDFactory.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/gradleConfigurations.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/internal/AbstractDokkaTaskExtensions.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinGradlePluginVersion.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinSourceSetGist.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/isMainSourceSet.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinCompilationUtils.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinSourceSetUtils.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/platformOfSourceSet.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/sourceSetKotlinGistConfiguration.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaLeafTask.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaParentTask.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaTask.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaCollectorTask.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaMultiModuleTask.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTask.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTaskPartial.kt delete mode 100644 runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/utils.kt delete mode 100644 runners/gradle-plugin/src/main/resources/META-INF/gradle-plugins/org.jetbrains.dokka.properties (limited to 'runners/gradle-plugin/src/main') diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaArtifacts.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaArtifacts.kt deleted file mode 100644 index 241c0449..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaArtifacts.kt +++ /dev/null @@ -1,29 +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.gradle - -import org.gradle.api.Project -import org.gradle.api.artifacts.Dependency -import org.jetbrains.dokka.DokkaVersion - -internal val Project.dokkaArtifacts get() = DokkaArtifacts(this) - -internal class DokkaArtifacts(private val project: Project) { - private fun fromModuleName(name: String): Dependency = - project.dependencies.create("org.jetbrains.dokka:$name:${DokkaVersion.version}") - - // TODO [beresnev] analysis switcher - val analysisKotlinDescriptors get() = fromModuleName("analysis-kotlin-descriptors") - val analysisKotlinSymbols get() = fromModuleName("analysis-kotlin-symbols") - - val allModulesPage get() = fromModuleName("all-modules-page-plugin") - val dokkaCore get() = fromModuleName("dokka-core") - val dokkaBase get() = fromModuleName("dokka-base") - val javadocPlugin get() = fromModuleName("javadoc-plugin") - val gfmPlugin get() = fromModuleName("gfm-plugin") - val gfmTemplateProcessing get() = fromModuleName("gfm-template-processing-plugin") - val jekyllTemplateProcessing get() = fromModuleName("jekyll-template-processing-plugin") - val jekyllPlugin get() = fromModuleName("jekyll-plugin") -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt deleted file mode 100644 index b6120129..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaMultiModuleFileLayout.kt +++ /dev/null @@ -1,94 +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.gradle - -import org.gradle.api.file.Directory -import org.gradle.api.provider.Provider -import org.jetbrains.dokka.DokkaException -import org.jetbrains.dokka.gradle.DokkaMultiModuleFileLayout.CompactInParent -import org.jetbrains.dokka.gradle.DokkaMultiModuleFileLayout.NoCopy -import java.io.File - -/** - * @see DokkaMultiModuleFileLayout.targetChildOutputDirectory - * @see NoCopy - * @see CompactInParent - */ -fun interface DokkaMultiModuleFileLayout { - - /** - * @param parent: The [DokkaMultiModuleTask] that is initiating a composite documentation run - * @param child: Some child task registered in [parent] - * @return The target output directory of the [child] dokka task referenced by [parent]. This should - * be unique for all registered child tasks. - */ - fun targetChildOutputDirectory(parent: DokkaMultiModuleTask, child: AbstractDokkaTask): Provider - - /** - * Will link to the original [AbstractDokkaTask.outputDirectory]. This requires no copying of the output files. - */ - object NoCopy : DokkaMultiModuleFileLayout { - override fun targetChildOutputDirectory( - parent: DokkaMultiModuleTask, - child: AbstractDokkaTask - ): Provider = child.outputDirectory - } - - /** - * Will point to a subfolder inside the output directory of the parent. - * The subfolder will follow the structure of the gradle project structure - * e.g. - * :parentProject:firstAncestor:secondAncestor will be be resolved to - * {parent output directory}/firstAncestor/secondAncestor - */ - object CompactInParent : DokkaMultiModuleFileLayout { - override fun targetChildOutputDirectory( - parent: DokkaMultiModuleTask, - child: AbstractDokkaTask - ): Provider { - val relativeProjectPath = parent.project.relativeProjectPath(child.project.path) - val relativeFilePath = relativeProjectPath.replace(":", File.separator) - check(!File(relativeFilePath).isAbsolute) { "Unexpected absolute path $relativeFilePath" } - return parent.outputDirectory.dir(relativeFilePath) - } - } -} - -internal fun DokkaMultiModuleTask.targetChildOutputDirectory( - child: AbstractDokkaTask -): Provider = fileLayout.get().targetChildOutputDirectory(this, child) - - -internal fun DokkaMultiModuleTask.copyChildOutputDirectories() { - childDokkaTasks.forEach { child -> - this.copyChildOutputDirectory(child) - } -} - -internal fun DokkaMultiModuleTask.copyChildOutputDirectory(child: AbstractDokkaTask) { - val targetChildOutputDirectory = project.file(fileLayout.get().targetChildOutputDirectory(this, child)) - val sourceChildOutputDirectory = child.outputDirectory.asFile.get() - - /* Pointing to the same directory -> No copy necessary */ - if (sourceChildOutputDirectory.absoluteFile == targetChildOutputDirectory.absoluteFile) { - return - } - - /* Cannot target *inside* the original folder */ - if (targetChildOutputDirectory.absoluteFile.startsWith(sourceChildOutputDirectory.absoluteFile)) { - throw DokkaException( - "Cannot re-locate output directory into itself.\n" + - "sourceChildOutputDirectory=${sourceChildOutputDirectory.path}\n" + - "targetChildOutputDirectory=${targetChildOutputDirectory.path}" - ) - } - - /* Source output directory is empty -> No copy necessary */ - if (!sourceChildOutputDirectory.exists()) { - return - } - - sourceChildOutputDirectory.copyRecursively(targetChildOutputDirectory, overwrite = true) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt deleted file mode 100644 index 77fba8f2..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaPlugin.kt +++ /dev/null @@ -1,131 +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.gradle - -import org.gradle.api.DefaultTask -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.artifacts.Dependency -import org.gradle.kotlin.dsl.register -import org.gradle.kotlin.dsl.withType -import org.gradle.util.GradleVersion -import org.jetbrains.dokka.DokkaDefaults - -open class DokkaPlugin : Plugin { - override fun apply(project: Project) { - if (GradleVersion.version(project.gradle.gradleVersion) < GradleVersion.version("5.6")) { - project.logger.warn("Dokka: Build is using unsupported gradle version, expected at least 5.6 but got ${project.gradle.gradleVersion}. This may result in strange errors") - } - if (project.shouldUseK2()) - project.logger.warn( - "Dokka's K2 Analysis is being used. " + - "It is still under active development and is thus experimental. " + - "It can be the cause of failed builds or incorrectly generated documentation. " + - "If you encounter an issue, please consider reporting it: https://github.com/Kotlin/dokka/issues" - ) - - project.setupDokkaTasks("dokkaHtml") { - description = "Generates documentation in 'html' format" - } - - project.setupDokkaTasks( - name = "dokkaJavadoc", - multiModuleTaskSupported = false - ) { - plugins.dependencies.add(project.dokkaArtifacts.javadocPlugin) - description = "Generates documentation in 'javadoc' format" - } - - project.setupDokkaTasks( - "dokkaGfm", - allModulesPageAndTemplateProcessing = project.dokkaArtifacts.gfmTemplateProcessing - ) { - plugins.dependencies.add(project.dokkaArtifacts.gfmPlugin) - description = "Generates documentation in GitHub flavored markdown format" - } - - project.setupDokkaTasks( - "dokkaJekyll", - allModulesPageAndTemplateProcessing = project.dokkaArtifacts.jekyllTemplateProcessing - ) { - plugins.dependencies.add(project.dokkaArtifacts.jekyllPlugin) - description = "Generates documentation in Jekyll flavored markdown format" - } - - project.configureEachAbstractDokkaTask() - project.configureEachDokkaMultiModuleTask() - } - - /** - * Creates [DokkaTask], [DokkaMultiModuleTask] for the given - * name and configuration. - */ - private fun Project.setupDokkaTasks( - name: String, - multiModuleTaskSupported: Boolean = true, - allModulesPageAndTemplateProcessing: Dependency = project.dokkaArtifacts.allModulesPage, - configuration: AbstractDokkaTask.() -> Unit = {} - ) { - project.maybeCreateDokkaPluginConfiguration(name) - project.maybeCreateDokkaRuntimeConfiguration(name) - project.tasks.register(name) { - configuration() - } - - if (project.parent != null) { - val partialName = "${name}Partial" - project.maybeCreateDokkaPluginConfiguration(partialName) - project.maybeCreateDokkaRuntimeConfiguration(partialName) - project.tasks.register(partialName) { - configuration() - } - } - - if (project.subprojects.isNotEmpty()) { - if (multiModuleTaskSupported) { - val multiModuleName = "${name}MultiModule" - project.maybeCreateDokkaPluginConfiguration(multiModuleName, setOf(allModulesPageAndTemplateProcessing)) - project.maybeCreateDokkaRuntimeConfiguration(multiModuleName) - - project.tasks.register(multiModuleName) { - @Suppress("DEPRECATION") - addSubprojectChildTasks("${name}Partial") - configuration() - description = "Runs all subprojects '$name' tasks and generates module navigation page" - } - - project.tasks.register("${name}Multimodule") { - group = "deprecated" - description = "DEPRECATED: 'Multimodule' is deprecated. Use 'MultiModule' instead." - dependsOn(multiModuleName) - doLast { - logger.warn("'Multimodule' is deprecated. Use 'MultiModule' instead") - } - } - } - - project.tasks.register("${name}Collector") { - @Suppress("DEPRECATION") - addSubprojectChildTasks(name) - description = - "Generates documentation merging all subprojects '$name' tasks into one virtual module" - } - } - } - - private fun Project.configureEachAbstractDokkaTask() { - tasks.withType().configureEach { - val formatClassifier = name.removePrefix("dokka").decapitalize() - outputDirectory.convention(project.layout.buildDirectory.dir("dokka/$formatClassifier")) - cacheRoot.convention(project.layout.dir(providers.provider { DokkaDefaults.cacheRoot })) - } - } - - private fun Project.configureEachDokkaMultiModuleTask() { - tasks.withType().configureEach { - sourceChildOutputDirectories.from({ childDokkaTasks.map { it.outputDirectory } }) - } - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaProperty.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaProperty.kt deleted file mode 100644 index 6c6e967d..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaProperty.kt +++ /dev/null @@ -1,10 +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.gradle - -import org.gradle.api.provider.Provider - - -internal fun Provider.getValidVersionOrNull() = orNull?.takeIf { it != "unspecified" } diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt deleted file mode 100644 index c0112719..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/DokkaSourceSetMapper.kt +++ /dev/null @@ -1,76 +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.gradle - -import org.jetbrains.dokka.* -import org.jetbrains.dokka.DokkaConfiguration.ExternalDocumentationLink -import java.io.File - -internal fun GradleDokkaSourceSetBuilder.toDokkaSourceSetImpl(): DokkaSourceSetImpl = DokkaSourceSetImpl( - classpath = classpath.toList(), - displayName = displayNameOrDefault(), - sourceSetID = sourceSetID, - sourceRoots = sourceRoots.toSet(), - dependentSourceSets = dependentSourceSets.get().toSet(), - samples = samples.toSet(), - includes = includes.toSet(), - includeNonPublic = includeNonPublic.get(), - documentedVisibilities = documentedVisibilities.get(), - reportUndocumented = reportUndocumented.get(), - skipEmptyPackages = skipEmptyPackages.get(), - skipDeprecated = skipDeprecated.get(), - jdkVersion = jdkVersion.get(), - sourceLinks = sourceLinks.get().build().toSet(), - perPackageOptions = perPackageOptions.get().build(), - externalDocumentationLinks = externalDocumentationLinksWithDefaults(), - languageVersion = languageVersion.orNull, - apiVersion = apiVersion.orNull, - noStdlibLink = noStdlibLink.get(), - noJdkLink = noJdkLink.get(), - suppressedFiles = suppressedFilesWithDefaults(), - analysisPlatform = platform.get() -) - -private fun GradleDokkaSourceSetBuilder.displayNameOrDefault(): String { - displayName.orNull?.let { return it } - if (name.endsWith("Main") && name != "Main") { - return name.removeSuffix("Main") - } - - return name -} - -private fun GradleDokkaSourceSetBuilder.externalDocumentationLinksWithDefaults(): Set { - return externalDocumentationLinks.get().build() - .run { - if (noJdkLink.get()) this - else this + ExternalDocumentationLink.jdk(jdkVersion.get()) - } - .run { - if (noStdlibLink.get()) this - else this + ExternalDocumentationLink.kotlinStdlib() - } - .run { - if (noAndroidSdkLink.get() || !project.isAndroidProject()) this - else this + - ExternalDocumentationLink.androidSdk() + - ExternalDocumentationLink.androidX() - } - .toSet() -} - -private fun GradleDokkaSourceSetBuilder.suppressedFilesWithDefaults(): Set { - val suppressedGeneratedFiles = if (suppressGeneratedFiles.get()) { - val generatedRoot = project.buildDir.resolve("generated").absoluteFile - sourceRoots - .filter { it.startsWith(generatedRoot) } - .flatMap { it.walk().toList() } - .toSet() - } else { - emptySet() - } - - return suppressedFiles.toSet() + suppressedGeneratedFiles -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt deleted file mode 100644 index aca3721a..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt +++ /dev/null @@ -1,483 +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.gradle - -import groovy.lang.Closure -import org.gradle.api.* -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.provider.ListProperty -import org.gradle.api.provider.Property -import org.gradle.api.provider.SetProperty -import org.gradle.api.tasks.* -import org.gradle.kotlin.dsl.listProperty -import org.gradle.kotlin.dsl.property -import org.gradle.kotlin.dsl.setProperty -import org.jetbrains.dokka.* -import java.io.File -import java.net.URL - -/** - * [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 - * import org.jetbrains.dokka.gradle.DokkaTask - * - * tasks.dokkaHtml { - * dokkaSourceSets { - * // configure individual source set by name - * named("customSourceSet") { - * suppress.set(true) - * } - * - * // configure all source sets at once - * configureEach { - * reportUndocumented.set(true) - * } - * } - * } - * ``` - */ -open class GradleDokkaSourceSetBuilder( - @Transient @get:Input val name: String, - @Transient @get:Internal internal val project: Project, - @Transient @get:Internal internal val sourceSetIdFactory: NamedDomainObjectFactory, -) : DokkaConfigurationBuilder { - - @Input - val sourceSetID: DokkaSourceSetID = sourceSetIdFactory.create(name) - - /** - * Whether this source set should be skipped when generating documentation. - * - * Default is `false`. - */ - @Input - val suppress: Property = project.objects.property() - .convention(false) - - /** - * 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. - */ - @Input - @Optional - val displayName: Property = project.objects.property() - - /** - * List of Markdown files that contain - * [module and package documentation](https://kotlinlang.org/docs/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. - * ``` - */ - @InputFiles - @Optional - @PathSensitive(PathSensitivity.RELATIVE) - val includes: ConfigurableFileCollection = project.files() - - /** - * 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 [GradlePackageOptionsBuilder.documentedVisibilities]. - * - * Default is [DokkaConfiguration.Visibility.PUBLIC]. - */ - @Input - val documentedVisibilities: SetProperty = - project.objects.setProperty() - .convention(DokkaDefaults.documentedVisibilities) - - /** - * 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. - * - * Prefer using [dependsOn] function to append dependent source sets to this list. - * - * By default, the values are deduced from information provided by the Kotlin Gradle plugin. - */ - @Input - val dependentSourceSets: SetProperty = project.objects.setProperty() - .convention(emptySet()) - - /** - * 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. - */ - @Classpath - @Optional - val classpath: ConfigurableFileCollection = project.files() - - /** - * Source code roots to be analyzed and documented. - * Accepts directories and individual `.kt` / `.java` files. - * - * Prefer using [sourceRoot] function to append source roots to this list. - * - * By default, source roots are deduced from information provided by the Kotlin Gradle plugin. - */ - @InputFiles - @PathSensitive(PathSensitivity.RELATIVE) - val sourceRoots: ConfigurableFileCollection = project.objects.fileCollection() - - /** - * 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. - */ - @InputFiles - @Optional - @PathSensitive(PathSensitivity.RELATIVE) - val samples: ConfigurableFileCollection = project.files() - - /** - * Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs - * after they have been filtered by [documentedVisibilities]. - * - * This setting works well with [AbstractDokkaTask.failOnWarning]. - * - * Can be overridden for a specific package by setting [GradlePackageOptionsBuilder.reportUndocumented]. - * - * Default is `false`. - */ - @Input - val reportUndocumented: Property = project.objects.property() - .convention(DokkaDefaults.reportUndocumented) - - /** - * Specifies the location of the project source code on the Web. If provided, Dokka generates - * "source" links for each declaration. See [GradleSourceLinkBuilder] for more details. - * - * Prefer using [sourceLink] action/closure for adding source links. - */ - @Nested - val sourceLinks: SetProperty = project.objects.setProperty() - .convention(emptySet()) - - /** - * Allows to customize documentation generation options on a per-package basis. - * - * @see GradlePackageOptionsBuilder for details - */ - @Nested - val perPackageOptions: ListProperty = - project.objects.listProperty() - .convention(emptyList()) - - /** - * Allows linking to Dokka/Javadoc documentation of the project's dependencies. - * - * Prefer using [externalDocumentationLink] action/closure for adding links. - */ - @Nested - val externalDocumentationLinks: SetProperty = - project.objects.setProperty() - .convention(emptySet()) - - /** - * Platform to be used for setting up code analysis and samples. - * - * The default value is deduced from information provided by the Kotlin Gradle plugin. - */ - @Input - @Optional - val platform: Property = project.objects.property() - .convention(Platform.DEFAULT) - - /** - * 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`. - */ - @Input - val skipEmptyPackages: Property = project.objects.property() - .convention(DokkaDefaults.skipEmptyPackages) - - /** - * Whether to document declarations annotated with [Deprecated]. - * - * Can be overridden on package level by setting [GradlePackageOptionsBuilder.skipDeprecated]. - * - * Default is `false`. - */ - @Input - val skipDeprecated: Property = project.objects.property() - .convention(DokkaDefaults.skipDeprecated) - - /** - * 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`. - */ - @InputFiles - @PathSensitive(PathSensitivity.RELATIVE) - val suppressedFiles: ConfigurableFileCollection = project.files() - - /** - * 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`. - */ - @Input - val suppressGeneratedFiles: Property = project.objects.property() - .convention(DokkaDefaults.suppressGeneratedFiles) - - /** - * 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 `false`, meaning links will be generated. - */ - @Input - val noStdlibLink: Property = project.objects.property() - .convention(DokkaDefaults.noStdlibLink) - - /** - * 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 `false`, meaning links will be generated. - */ - @Input - val noJdkLink: Property = project.objects.property() - .convention(DokkaDefaults.noJdkLink) - - /** - * 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 be generated. - */ - @Input - val noAndroidSdkLink: Property = project.objects.property() - .convention(DokkaDefaults.noAndroidSdkLink) - - /** - * [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. - */ - @Input - @Optional - val languageVersion: Property = project.objects.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]. - */ - @Input - @Optional - val apiVersion: Property = project.objects.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. - */ - @Input - val jdkVersion: Property = project.objects.property() - .convention(DokkaDefaults.jdkVersion) - - /** - * Deprecated. Use [documentedVisibilities] instead. - */ - @Input - val includeNonPublic: Property = project.objects.property() - .convention(DokkaDefaults.includeNonPublic) - - fun DokkaSourceSetID(sourceSetName: String): DokkaSourceSetID = sourceSetIdFactory.create(sourceSetName) - - /** - * Convenient override to **append** source sets to [dependentSourceSets] - */ - fun dependsOn(sourceSet: SourceSet) { - dependsOn(DokkaSourceSetID(sourceSet.name)) - } - - /** - * Convenient override to **append** source sets to [dependentSourceSets] - */ - fun dependsOn(sourceSet: GradleDokkaSourceSetBuilder) { - dependsOn(sourceSet.sourceSetID) - } - - /** - * Convenient override to **append** source sets to [dependentSourceSets] - */ - fun dependsOn(sourceSet: DokkaConfiguration.DokkaSourceSet) { - dependsOn(sourceSet.sourceSetID) - } - - /** - * Convenient override to **append** source sets to [dependentSourceSets] - */ - fun dependsOn(sourceSetName: String) { - dependsOn(DokkaSourceSetID(sourceSetName)) - } - - /** - * Convenient override to **append** source sets to [dependentSourceSets] - */ - fun dependsOn(sourceSetID: DokkaSourceSetID) { - dependentSourceSets.add(sourceSetID) - } - - /** - * Convenient override to **append** source roots to [sourceRoots] - */ - fun sourceRoot(file: File) { - sourceRoots.from(file) - } - - /** - * Convenient override to **append** source roots to [sourceRoots] - */ - fun sourceRoot(path: String) { - sourceRoot(project.file(path)) - } - - /** - * Closure for configuring source links, appending to [sourceLinks]. - * - * @see [GradleSourceLinkBuilder] for details. - */ - @Suppress("DEPRECATION") - fun sourceLink(c: Closure) { - val configured = org.gradle.util.ConfigureUtil.configure(c, GradleSourceLinkBuilder(project)) - sourceLinks.add(configured) - } - - /** - * Action for configuring source links, appending to [sourceLinks]. - * - * @see [GradleSourceLinkBuilder] for details. - */ - fun sourceLink(action: Action) { - val sourceLink = GradleSourceLinkBuilder(project) - action.execute(sourceLink) - sourceLinks.add(sourceLink) - } - - /** - * Closure for configuring package options, appending to [perPackageOptions]. - * - * @see [GradlePackageOptionsBuilder] for details. - */ - @Suppress("DEPRECATION") - fun perPackageOption(c: Closure) { - val configured = org.gradle.util.ConfigureUtil.configure(c, GradlePackageOptionsBuilder(project)) - perPackageOptions.add(configured) - } - - /** - * Action for configuring package options, appending to [perPackageOptions]. - * - * @see [GradlePackageOptionsBuilder] for details. - */ - fun perPackageOption(action: Action) { - val option = GradlePackageOptionsBuilder(project) - action.execute(option) - perPackageOptions.add(option) - } - - /** - * Closure for configuring external documentation links, appending to [externalDocumentationLinks]. - * - * @see [GradleExternalDocumentationLinkBuilder] for details. - */ - @Suppress("DEPRECATION") - fun externalDocumentationLink(c: Closure) { - val link = org.gradle.util.ConfigureUtil.configure(c, GradleExternalDocumentationLinkBuilder(project)) - externalDocumentationLinks.add(link) - } - - /** - * Action for configuring external documentation links, appending to [externalDocumentationLinks]. - * - * See [GradleExternalDocumentationLinkBuilder] for details. - */ - fun externalDocumentationLink(action: Action) { - val link = GradleExternalDocumentationLinkBuilder(project) - action.execute(link) - externalDocumentationLinks.add(link) - } - - /** - * Convenient override to **append** external documentation links to [externalDocumentationLinks]. - */ - fun externalDocumentationLink(url: String, packageListUrl: String? = null) { - externalDocumentationLink(URL(url), packageListUrl = packageListUrl?.let(::URL)) - } - - /** - * Convenient override to **append** external documentation links to [externalDocumentationLinks]. - */ - fun externalDocumentationLink(url: URL, packageListUrl: URL? = null) { - externalDocumentationLinks.add( - GradleExternalDocumentationLinkBuilder(project).apply { - this.url.convention(url) - if (packageListUrl != null) { - this.packageListUrl.convention(packageListUrl) - } - } - ) - } - - override fun build(): DokkaSourceSetImpl = toDokkaSourceSetImpl() -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.kt deleted file mode 100644 index fd962acc..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderExtensions.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.gradle - -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet - -/** - * Convenient override to **append** source sets to [GradleDokkaSourceSetBuilder.dependentSourceSets] - */ -fun GradleDokkaSourceSetBuilder.dependsOn(sourceSet: KotlinSourceSet) { - dependsOn(DokkaSourceSetID(sourceSet.name)) -} - -/** - * Convenient override to **append** source sets to [GradleDokkaSourceSetBuilder.dependentSourceSets] - */ -fun GradleDokkaSourceSetBuilder.dependsOn(@Suppress("DEPRECATION") sourceSet: com.android.build.gradle.api.AndroidSourceSet) { - dependsOn(DokkaSourceSetID(sourceSet.name)) -} - -/** - * Convenient override to **append** source sets to [GradleDokkaSourceSetBuilder.dependentSourceSets] - */ -fun GradleDokkaSourceSetBuilder.dependsOn(@Suppress("UnstableApiUsage") sourceSet: com.android.build.api.dsl.AndroidSourceSet) { - dependsOn(DokkaSourceSetID(sourceSet.name)) -} - -/** - * Extension allowing configuration of Dokka source sets via Kotlin Gradle plugin source sets. - */ -fun GradleDokkaSourceSetBuilder.kotlinSourceSet(kotlinSourceSet: KotlinSourceSet) { - configureWithKotlinSourceSet(kotlinSourceSet) -} - diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderFactory.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderFactory.kt deleted file mode 100644 index b2fc0394..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderFactory.kt +++ /dev/null @@ -1,12 +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.gradle - -import org.gradle.api.NamedDomainObjectFactory - -@Suppress("ObjectLiteralToLambda") // Will fail at runtime in Gradle versions <= 6.6 -fun AbstractDokkaTask.gradleDokkaSourceSetBuilderFactory(): NamedDomainObjectFactory = - NamedDomainObjectFactory { name -> GradleDokkaSourceSetBuilder(name, project, DokkaSourceSetIdFactory()) } - diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt deleted file mode 100644 index 2420583c..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleExternalDocumentationLinkBuilder.kt +++ /dev/null @@ -1,80 +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.gradle - -import org.gradle.api.Project -import org.gradle.api.provider.Property -import org.gradle.api.tasks.Input -import org.gradle.api.tasks.Internal -import org.gradle.api.tasks.Optional -import org.gradle.kotlin.dsl.property -import org.jetbrains.dokka.DokkaConfigurationBuilder -import org.jetbrains.dokka.ExternalDocumentationLink -import org.jetbrains.dokka.ExternalDocumentationLinkImpl -import java.net.URL - -/** - * 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(URL("https://kotlinlang.org/api/kotlinx.serialization/")) - * packageListUrl.set( - * rootProject.projectDir.resolve("serialization.package.list").toURL() - * ) - * } - * ``` - */ -class GradleExternalDocumentationLinkBuilder( - @Transient @get:Internal internal val project: Project -) : DokkaConfigurationBuilder { - - /** - * Root URL of documentation to link with. **Must** contain a trailing slash. - * - * 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.URL("https://kotlinlang.org/api/kotlinx.serialization/") - * ``` - */ - @Input - val url: Property = project.objects.property() - - /** - * 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() - * ``` - */ - @Optional - @Input - val packageListUrl: Property = project.objects.property() - - override fun build(): ExternalDocumentationLinkImpl = ExternalDocumentationLink( - url = checkNotNull(url.get()) { "url not specified " }, - packageListUrl = packageListUrl.orNull, - ) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt deleted file mode 100644 index 93b1f52c..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt +++ /dev/null @@ -1,113 +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.gradle - -import org.gradle.api.Project -import org.gradle.api.provider.Property -import org.gradle.api.provider.SetProperty -import org.gradle.api.tasks.Input -import org.gradle.api.tasks.Internal -import org.gradle.kotlin.dsl.* -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.DokkaConfigurationBuilder -import org.jetbrains.dokka.DokkaDefaults -import org.jetbrains.dokka.PackageOptionsImpl - -/** - * 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) - * } - * } - * } - * ``` - */ -class GradlePackageOptionsBuilder( - @Transient @get:Internal internal val project: Project -) : DokkaConfigurationBuilder { - - /** - * Regular expression that is used to match the package. - * - * Default is any string: `.*`. - */ - @Input - val matchingRegex: Property = project.objects.property() - .convention(".*") - - /** - * Whether this package should be skipped when generating documentation. - * - * Default is `false`. - */ - @Input - val suppress: Property = project.objects.property() - .convention(DokkaDefaults.suppress) - - /** - * 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 [GradleDokkaSourceSetBuilder.documentedVisibilities]. - * - * Default is [DokkaConfiguration.Visibility.PUBLIC]. - */ - @Input - val documentedVisibilities: SetProperty = - project.objects.setProperty() - .convention(DokkaDefaults.documentedVisibilities) - - /** - * Whether to document declarations annotated with [Deprecated]. - * - * Can be overridden on source set level by setting [GradleDokkaSourceSetBuilder.skipDeprecated]. - * - * Default is `false`. - */ - @Input - val skipDeprecated: Property = project.objects.property() - .convention(DokkaDefaults.skipDeprecated) - - /** - * Whether to emit warnings about visible undocumented declarations, that is declarations from - * this package and without KDocs, after they have been filtered by [documentedVisibilities]. - * - * This setting works well with [AbstractDokkaTask.failOnWarning]. - * - * Can be overridden on source set level by setting [GradleDokkaSourceSetBuilder.reportUndocumented]. - * - * Default is `false`. - */ - @Input - val reportUndocumented: Property = project.objects.property() - .convention(DokkaDefaults.reportUndocumented) - - /** - * Deprecated. Use [documentedVisibilities] instead. - */ - @Input - val includeNonPublic: Property = project.objects.property() - .convention(DokkaDefaults.includeNonPublic) - - - override fun build(): PackageOptionsImpl = PackageOptionsImpl( - matchingRegex = matchingRegex.get(), - includeNonPublic = includeNonPublic.get(), - documentedVisibilities = documentedVisibilities.get(), - reportUndocumented = reportUndocumented.get(), - skipDeprecated = skipDeprecated.get(), - suppress = suppress.get() - ) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt deleted file mode 100644 index 817e5ab9..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleSourceLinkBuilder.kt +++ /dev/null @@ -1,102 +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.gradle - -import org.gradle.api.Project -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.tasks.* -import org.gradle.kotlin.dsl.property -import org.jetbrains.dokka.DokkaConfigurationBuilder -import org.jetbrains.dokka.SourceLinkDefinitionImpl -import java.io.File -import java.net.URL - -/** - * 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(URL("https://github.com/kotlin/dokka/tree/master/src")) - * remoteLineSuffix.set("#L") - * } - * ``` - */ -class GradleSourceLinkBuilder( - @Transient @get:Internal internal val project: Project -) : DokkaConfigurationBuilder { - - /** - * 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") - * ``` - */ - @Internal // changing contents of the directory should not invalidate the task - val localDirectory: Property = project.objects.property() - - /** - * 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. - */ - @Suppress("unused") - @get:Input - internal val localDirectoryPath: Provider = - localDirectory.map { it.relativeToOrSelf(project.projectDir).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.URL("https://github.com/username/projectname/tree/master/src")) - * ``` - */ - @Input - val remoteUrl: Property = project.objects.property() - - /** - * 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`. - */ - @Optional - @Input - val remoteLineSuffix: Property = project.objects.property() - .convention("#L") - - override fun build(): SourceLinkDefinitionImpl { - return SourceLinkDefinitionImpl( - localDirectory = localDirectory.orNull?.canonicalPath ?: project.projectDir.canonicalPath, - remoteUrl = remoteUrl.get(), - remoteLineSuffix = remoteLineSuffix.get(), - ) - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/TaskDependencyInternalWithAdditions.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/TaskDependencyInternalWithAdditions.kt deleted file mode 100644 index d3469f69..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/TaskDependencyInternalWithAdditions.kt +++ /dev/null @@ -1,22 +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.gradle - -import org.gradle.api.Task -import org.gradle.api.internal.tasks.DefaultTaskDependency -import org.gradle.api.internal.tasks.TaskDependencyInternal - -internal operator fun TaskDependencyInternal.plus(tasks: Iterable): TaskDependencyInternal = - TaskDependencyInternalWithAdditions(this, tasks.toSet()) - -private class TaskDependencyInternalWithAdditions( - dependency: TaskDependencyInternal, - additionalTaskDependencies: Set, -) : DefaultTaskDependency() { - - init { - add(dependency, additionalTaskDependencies) - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/automagicTypedProxy.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/automagicTypedProxy.kt deleted file mode 100644 index 8e397a4a..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/automagicTypedProxy.kt +++ /dev/null @@ -1,49 +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.gradle - -import java.lang.reflect.InvocationHandler -import java.lang.reflect.InvocationTargetException -import java.lang.reflect.Method -import java.lang.reflect.Proxy - - -/** - * Warning! Hard reflection magic used here. - * - * Creates [java.lang.reflect.Proxy] with pass through invocation algorithm, - * to create access proxy for [delegate] into [targetClassLoader]. - */ -internal inline fun automagicTypedProxy(targetClassLoader: ClassLoader, delegate: Any): T = - automagicProxy(targetClassLoader, T::class.java, delegate) as T - - -/** - * Warning! Hard reflection magic used here. - * - * Creates [java.lang.reflect.Proxy] with pass through invocation algorithm, - * to create access proxy for [delegate] into [targetClassLoader]. - * - */ -private fun automagicProxy(targetClassLoader: ClassLoader, targetType: Class<*>, delegate: Any): Any = - Proxy.newProxyInstance( - targetClassLoader, - arrayOf(targetType), - DelegatedInvocationHandler(delegate) - ) - -private class DelegatedInvocationHandler(private val delegate: Any) : InvocationHandler { - - @Throws(Throwable::class) - override fun invoke(proxy: Any, method: Method, args: Array?): Any? { - val delegateMethod = delegate.javaClass.getMethod(method.name, *method.parameterTypes) - try { - delegateMethod.isAccessible = true - return delegateMethod.invoke(delegate, *(args ?: emptyArray())) - } catch (ex: InvocationTargetException) { - throw ex.targetException - } - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkChildDokkaTasksIsNotEmpty.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkChildDokkaTasksIsNotEmpty.kt deleted file mode 100644 index 64fc1f9f..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkChildDokkaTasksIsNotEmpty.kt +++ /dev/null @@ -1,47 +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.gradle - -import org.jetbrains.dokka.DokkaException - -internal fun AbstractDokkaParentTask.checkChildDokkaTasksIsNotEmpty() { - if (childDokkaTaskPaths.isEmpty()) { - throw DokkaException( - """ - The ${this::class.java.simpleName} $path has no configured child tasks. - Add some dokka tasks like e.g.: - - tasks.named("$name") { - addChildTask(..) - addChildTasks(subprojects, "...") - //... - } - """.trimIndent() - ) - } - - if (childDokkaTasks.isEmpty()) { - throw DokkaException( - """ - The ${this::class.java.simpleName} $path could not find any registered child task. - child tasks: $childDokkaTaskPaths - - Please make sure to apply the dokka plugin to all included (sub)-projects individually e.g.: - - // subproject build.gradle.kts - plugins { - id("org.jetbrains.dokka") - } - - or - - // parent build.gradle.kts - subprojects { - plugins.apply("org.jetbrains.dokka") - } - """ - ) - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkDependentSourceSets.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkDependentSourceSets.kt deleted file mode 100644 index 630f2dca..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/checkDependentSourceSets.kt +++ /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 org.jetbrains.dokka.gradle - -import org.jetbrains.dokka.DokkaSourceSetID - -internal fun checkSourceSetDependencies(sourceSets: List) { - checkSourceSetDependencies(sourceSets.associateBy { it.sourceSetID }) -} - -private fun checkSourceSetDependencies(sourceSets: Map) { - sourceSets.values.forEach { sourceSet -> - sourceSet.dependentSourceSets.get().forEach { dependentSourceSetID -> - val dependentSourceSet = requireNotNull(sourceSets[dependentSourceSetID]) { - "Dokka source set \"${sourceSet.name}\": Cannot find dependent source set \"$dependentSourceSetID\"" - } - - if (sourceSet.suppress.get().not() && dependentSourceSet.suppress.get()) { - throw IllegalArgumentException( - "Dokka source set: \"${sourceSet.name}\": " + - "Unsuppressed source set cannot depend on suppressed source set \"$dependentSourceSetID\"" - ) - } - } - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaBootstrapFactory.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaBootstrapFactory.kt deleted file mode 100644 index 21a2e8d1..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaBootstrapFactory.kt +++ /dev/null @@ -1,22 +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.gradle - -import org.gradle.api.artifacts.Configuration -import org.jetbrains.dokka.DokkaBootstrap -import java.net.URLClassLoader -import kotlin.reflect.KClass - -fun DokkaBootstrap(configuration: Configuration, bootstrapClass: KClass): DokkaBootstrap { - val runtimeJars = configuration.resolve() - val runtimeClassLoader = URLClassLoader( - runtimeJars.map { it.toURI().toURL() }.toTypedArray(), - ClassLoader.getSystemClassLoader().parent - ) - - val runtimeClassloaderBootstrapClass = runtimeClassLoader.loadClass(bootstrapClass.qualifiedName) - val runtimeClassloaderBootstrapInstance = runtimeClassloaderBootstrapClass.constructors.first().newInstance() - return automagicTypedProxy(DokkaPlugin::class.java.classLoader, runtimeClassloaderBootstrapInstance) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaDefaultOutputDirectory.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaDefaultOutputDirectory.kt deleted file mode 100644 index d92b84a1..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaDefaultOutputDirectory.kt +++ /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 org.jetbrains.dokka.gradle - -import org.gradle.api.Task -import java.io.File - -internal fun Task.defaultDokkaOutputDirectory(): File { - return defaultDokkaOutputDirectory(project.buildDir, name) -} - -internal fun defaultDokkaOutputDirectory(buildDir: File, taskName: String): File { - val formatClassifier = taskName.removePrefix("dokka").decapitalize() - return File(buildDir, "dokka${File.separator}$formatClassifier") -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaSourceSetIDFactory.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaSourceSetIDFactory.kt deleted file mode 100644 index b658e5f6..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/dokkaSourceSetIDFactory.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.gradle - -import org.gradle.api.NamedDomainObjectFactory -import org.gradle.api.Task -import org.jetbrains.dokka.DokkaSourceSetID - -internal fun DokkaSourceSetID(task: Task, sourceSetName: String): DokkaSourceSetID { - return DokkaSourceSetID(task.path, sourceSetName) -} - -@Suppress("FunctionName") -internal fun Task.DokkaSourceSetIdFactory() = NamedDomainObjectFactory { name -> - DokkaSourceSetID(this@DokkaSourceSetIdFactory, name) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/gradleConfigurations.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/gradleConfigurations.kt deleted file mode 100644 index 63424e1e..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/gradleConfigurations.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.gradle - -import org.gradle.api.Project -import org.gradle.api.artifacts.Configuration -import org.gradle.api.artifacts.Dependency -import org.gradle.api.attributes.Usage -import org.gradle.kotlin.dsl.named - -internal fun Project.shouldUseK2() = - (findProperty("org.jetbrains.dokka.experimental.tryK2") as? String)?.toBoolean() ?: false - -internal fun Project.maybeCreateDokkaDefaultPluginConfiguration(): Configuration { - return configurations.maybeCreate("dokkaPlugin") { - attributes.attribute(Usage.USAGE_ATTRIBUTE, project.objects.named(Usage.JAVA_RUNTIME)) - isCanBeConsumed = false - } -} - -internal fun Project.maybeCreateDokkaDefaultRuntimeConfiguration(): Configuration { - return configurations.maybeCreate("dokkaRuntime") { - attributes.attribute(Usage.USAGE_ATTRIBUTE, project.objects.named(Usage.JAVA_RUNTIME)) - isCanBeConsumed = false - } -} - -internal fun Project.maybeCreateDokkaPluginConfiguration(dokkaTaskName: String, additionalDependencies: Collection = emptySet()): Configuration { - return project.configurations.maybeCreate("${dokkaTaskName}Plugin") { - extendsFrom(maybeCreateDokkaDefaultPluginConfiguration()) - attributes.attribute(Usage.USAGE_ATTRIBUTE, project.objects.named(Usage.JAVA_RUNTIME)) - isCanBeConsumed = false - dependencies.add( - if (shouldUseK2()) project.dokkaArtifacts.analysisKotlinSymbols - else project.dokkaArtifacts.analysisKotlinDescriptors - ) - dependencies.add(project.dokkaArtifacts.dokkaBase) - dependencies.addAll(additionalDependencies) - } -} - -internal fun Project.maybeCreateDokkaRuntimeConfiguration(dokkaTaskName: String): Configuration { - return project.configurations.maybeCreate("${dokkaTaskName}Runtime") { - extendsFrom(maybeCreateDokkaDefaultRuntimeConfiguration()) - attributes.attribute(Usage.USAGE_ATTRIBUTE, project.objects.named(Usage.JAVA_RUNTIME)) - isCanBeConsumed = false - defaultDependencies { - add(project.dokkaArtifacts.dokkaCore) - } - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/internal/AbstractDokkaTaskExtensions.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/internal/AbstractDokkaTaskExtensions.kt deleted file mode 100644 index 7675c69b..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/internal/AbstractDokkaTaskExtensions.kt +++ /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 org.jetbrains.dokka.gradle.internal - -import org.jetbrains.dokka.InternalDokkaApi -import org.jetbrains.dokka.gradle.AbstractDokkaTask -import org.jetbrains.dokka.toPrettyJsonString -import org.jetbrains.dokka.DokkaConfiguration -import org.jetbrains.dokka.toCompactJsonString - -/** - * Serializes [DokkaConfiguration] of this [AbstractDokkaTask] as json - * - * Should be used for short-term debugging only, no guarantees are given for the support of this API. - * - * Better alternative should be introduced as part of [#2873](https://github.com/Kotlin/dokka/issues/2873). - */ -@InternalDokkaApi -fun AbstractDokkaTask.buildJsonConfiguration(prettyPrint: Boolean = true): String { - val configuration = this.buildDokkaConfiguration() - return if (prettyPrint) { - configuration.toPrettyJsonString() - } else { - configuration.toCompactJsonString() - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinGradlePluginVersion.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinGradlePluginVersion.kt deleted file mode 100644 index 72f1a626..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinGradlePluginVersion.kt +++ /dev/null @@ -1,34 +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.gradle.kotlin - -import org.gradle.api.Project -import org.jetbrains.kotlin.gradle.plugin.getKotlinPluginVersion - -internal typealias KotlinGradlePluginVersion = KotlinVersion - -internal fun Project.getKgpVersion(): KotlinGradlePluginVersion? = parseKotlinVersion(this.getKotlinPluginVersion()) - -/** - * Accepts a full version string that contains the major, minor - * and patch versions divided by dots, such as "1.7.10". - * - * Does NOT parse and store custom suffixes, so `1.8.20-RC2` - * or `1.8.20-dev-42` will be viewed as `1.8.20`. - */ -internal fun parseKotlinVersion(fullVersionString: String): KotlinVersion? { - val versionParts = fullVersionString - .split(".", "-", limit = 4) - .takeIf { parts -> parts.size >= 3 && parts.subList(0, 3).all { it.isNumeric() } } - ?: return null - - return KotlinVersion( - major = versionParts[0].toInt(), - minor = versionParts[1].toInt(), - patch = versionParts[2].toInt() - ) -} - -private fun String.isNumeric() = this.isNotEmpty() && this.all { it.isDigit() } diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt deleted file mode 100644 index 3180efef..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinNativeDistributionAccessor.kt +++ /dev/null @@ -1,39 +0,0 @@ -@file:Suppress("INVISIBLE_REFERENCE") -package org.jetbrains.dokka.gradle.kotlin - -import java.io.File -import org.gradle.api.Project -import org.jetbrains.kotlin.commonizer.KonanDistribution -import org.jetbrains.kotlin.commonizer.platformLibsDir -import org.jetbrains.kotlin.commonizer.stdlib -import org.jetbrains.kotlin.compilerRunner.konanHome -import org.jetbrains.kotlin.konan.target.KonanTarget - -/** - * Provides access to the Kotlin/Native distribution components: - * * [stdlibDir] -- stdlib directory - * * [platformDependencies] -- list of directories to platform dependencies - * - * It uses Kotlin Gradle Plugin API that is guaranteed to be present in: - * 1.5 <= kotlinVersion <= 1.9 - * - * It should not be used with Kotlin versions later than 1.9 - */ -internal class KotlinNativeDistributionAccessor( - project: Project -) { - private val konanDistribution = KonanDistribution( - @Suppress("INVISIBLE_MEMBER") - project.konanHome - ) - - val stdlibDir: File = konanDistribution.stdlib - - fun platformDependencies(target: KonanTarget): List = konanDistribution - .platformLibsDir - .resolve(target.name) - .listLibraryFiles() - - private fun File.listLibraryFiles(): List = listFiles().orEmpty() - .filter { it.isDirectory || it.extension == "klib" } -} \ No newline at end of file diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinSourceSetGist.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinSourceSetGist.kt deleted file mode 100644 index 18d7ebb2..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/KotlinSourceSetGist.kt +++ /dev/null @@ -1,33 +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.gradle.kotlin - -import org.gradle.api.Project -import org.gradle.api.file.FileCollection -import org.gradle.api.provider.Provider -import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet - -internal data class KotlinSourceSetGist( - val name: String, - val platform: Provider, - val isMain: Provider, - val classpath: Provider, - val sourceRoots: FileCollection, - val dependentSourceSetNames: Provider>, -) - -internal fun Project.gistOf(sourceSet: KotlinSourceSet): KotlinSourceSetGist = KotlinSourceSetGist( - name = sourceSet.name, - platform = project.provider { platformOf(sourceSet) }, - isMain = project.provider { isMainSourceSet(sourceSet) }, - classpath = project.provider { classpathOf(sourceSet).filter { it.exists() } }, - // TODO: Needs to respect filters. - // We probably need to change from "sourceRoots" to support "sourceFiles" - // https://github.com/Kotlin/dokka/issues/1215 - sourceRoots = sourceSet.kotlin.sourceDirectories.filter { it.exists() }, - dependentSourceSetNames = project.provider { sourceSet.dependsOn.map { it.name }.toSet() }, -) - diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/isMainSourceSet.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/isMainSourceSet.kt deleted file mode 100644 index b8abaca3..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/isMainSourceSet.kt +++ /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. - */ - -package org.jetbrains.dokka.gradle.kotlin - -import com.android.build.gradle.api.ApplicationVariant -import com.android.build.gradle.api.LibraryVariant -import org.gradle.api.Project -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet -import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinJvmAndroidCompilation - -internal fun Project.isMainSourceSet(sourceSet: KotlinSourceSet): Boolean { - return isMainSourceSet(allCompilationsOf(sourceSet)) -} - -internal fun isMainSourceSet(compilations: List): Boolean { - return compilations.any { compilation -> isMainCompilation(compilation) } -} - -private fun isMainCompilation(compilation: KotlinCompilation): Boolean { - try { - val androidVariant = compilation.run { this as? KotlinJvmAndroidCompilation }?.androidVariant - if (androidVariant != null) { - return androidVariant is LibraryVariant || androidVariant is ApplicationVariant - } - } catch (e: NoSuchMethodError) { - // Kotlin Plugin version below 1.4 - return !compilation.name.toLowerCase().endsWith("test") - } - return compilation.name == "main" -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.kt deleted file mode 100644 index 778261a7..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinClasspathUtils.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.gradle.kotlin - -import org.gradle.api.Project -import org.gradle.api.file.FileCollection -import org.jetbrains.dokka.gradle.isAndroidTarget -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet -import org.jetbrains.kotlin.gradle.plugin.mpp.AbstractKotlinNativeCompilation -import org.jetbrains.kotlin.gradle.tasks.KotlinCompile - -internal fun Project.classpathOf(sourceSet: KotlinSourceSet): FileCollection { - val compilations = compilationsOf(sourceSet) - return if (compilations.isNotEmpty()) { - compilations - .map { compilation -> compilation.compileClasspathOf(project = this) } - .reduce(FileCollection::plus) - } else { - // Dokka suppresses source sets that do no have compilations - // since such configuration is invalid, it reports a warning or an error - sourceSet.withAllDependentSourceSets() - .map { it.kotlin.sourceDirectories } - .reduce(FileCollection::plus) - } -} - -private fun KotlinCompilation.compileClasspathOf(project: Project): FileCollection { - val kgpVersion = project.getKgpVersion() - - // if KGP version < 1.9 or org.jetbrains.dokka.classpath.useOldResolution=true - // we will use old (pre 1.9) resolution of classpath - if (kgpVersion == null || - kgpVersion < KotlinGradlePluginVersion(1, 9, 0) || - project.classpathProperty("useOldResolution", default = false) - ) { - return oldCompileClasspathOf(project) - } - - return newCompileClasspathOf(project) -} - -private fun KotlinCompilation.newCompileClasspathOf(project: Project): FileCollection { - if (this.target.isAndroidTarget()) { // Workaround for https://youtrack.jetbrains.com/issue/KT-33893 - return this.classpathOf(project) - } - - val result = project.objects.fileCollection() - result.from({ compileDependencyFiles }) - - val kgpVersion = project.getKgpVersion() - // Since Kotlin 2.0 native distributiuon dependencies will be included to compileDependencyFiles - if (kgpVersion != null && kgpVersion <= KotlinGradlePluginVersion(1, 9, 255)) { - if (this is AbstractKotlinNativeCompilation) { - val kotlinNativeDistributionAccessor = KotlinNativeDistributionAccessor(project) - result.from(kotlinNativeDistributionAccessor.stdlibDir) - result.from(kotlinNativeDistributionAccessor.platformDependencies(konanTarget)) - } - } - - return result -} - -private fun KotlinCompilation.oldCompileClasspathOf(project: Project): FileCollection { - if (this.target.isAndroidTarget()) { // Workaround for https://youtrack.jetbrains.com/issue/KT-33893 - return this.classpathOf(project) - } - - return this.compileDependencyFiles + platformDependencyFiles(project) + this.classpathOf(project) -} - -private fun KotlinCompilation.classpathOf(project: Project): FileCollection { - val kgpVersion = project.getKgpVersion() - val kotlinCompile = this.getKotlinCompileTask(kgpVersion) ?: return project.files() - - val shouldKeepBackwardsCompatibility = (kgpVersion != null && kgpVersion < KotlinGradlePluginVersion(1, 7, 0)) - return if (shouldKeepBackwardsCompatibility) { - // removed since 1.9.0, left for compatibility with < Kotlin 1.7 - val classpathGetter = kotlinCompile::class.members - .first { it.name == "getClasspath" } - classpathGetter.call(kotlinCompile) as FileCollection - } else { - kotlinCompile.libraries // introduced in 1.7.0 - } -} - -private fun KotlinCompilation.getKotlinCompileTask(kgpVersion: KotlinGradlePluginVersion? = null): KotlinCompile? { - val shouldKeepBackwardsCompatibility = (kgpVersion != null && kgpVersion < KotlinGradlePluginVersion(1, 8, 0)) - return if (shouldKeepBackwardsCompatibility) { - @Suppress("DEPRECATION") // for `compileKotlinTask` property, deprecated with warning since 1.8.0 - this.compileKotlinTask as? KotlinCompile - } else { - this.compileTaskProvider.get() as? KotlinCompile // introduced in 1.8.0 - } -} - -private fun KotlinCompilation.platformDependencyFiles(project: Project): FileCollection { - val excludePlatformDependencyFiles = project.classpathProperty("excludePlatformDependencyFiles", default = false) - - if (excludePlatformDependencyFiles) return project.files() - return (this as? AbstractKotlinNativeCompilation) - ?.target?.project?.configurations - ?.findByName(@Suppress("DEPRECATION") this.defaultSourceSet.implementationMetadataConfigurationName) // KT-58640 - ?: project.files() -} - -private fun Project.classpathProperty(name: String, default: Boolean): Boolean = - (findProperty("org.jetbrains.dokka.classpath.$name") as? String)?.toBoolean() ?: default diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinCompilationUtils.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinCompilationUtils.kt deleted file mode 100644 index 0b1b7419..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinCompilationUtils.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.gradle.kotlin - -import org.gradle.api.Project -import org.jetbrains.dokka.gradle.kotlin -import org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptions -import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension -import org.jetbrains.kotlin.gradle.dsl.KotlinSingleTargetExtension -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet -import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinCommonCompilation - -internal typealias KotlinCompilation = - org.jetbrains.kotlin.gradle.plugin.KotlinCompilation - -internal fun Project.compilationsOf(sourceSet: KotlinSourceSet): List { - //KT-45412 Make sure .kotlinSourceSets and .allKotlinSourceSets include the default source set - val compilations = allCompilationsOf(sourceSet).filter { compilation -> - sourceSet in compilation.kotlinSourceSets || sourceSet == compilation.defaultSourceSet - } - - val hasAdditionalCommonCompatibilityMetadataVariant = compilations.size >= 2 - && this.isHmppEnabled() - && compilations.any { it is KotlinCommonCompilation && it.compilationName == "main" } - && compilations.any { it is KotlinCommonCompilation && it.compilationName == "commonMain" } - - return if (hasAdditionalCommonCompatibilityMetadataVariant) { - // If the project has `kotlin.mpp.enableCompatibilityMetadataVariant` set to `true` - // and it produces a legacy variant for common, we filter it out because one of the dependencies - // might be published without it, and it would lead to the following error: - // - // > Execution failed for task ':project:dokkaHtmlPartial'. - // > Could not resolve all files for configuration ':project:metadataCompileClasspath'. - // > Could not resolve com.example.dependency:0.1.0. - // > The consumer was configured to find a usage of 'kotlin-api' of a library, preferably optimized for - // non-jvm, as well as attribute 'org.jetbrains.kotlin.platform.type' with value 'common'. However we - // cannot choose between the following variants of com.example.dependency:0.1.0: - // - // This can be reproduced consistently on Ktor of version 2.3.2 - compilations.filterNot { it is KotlinCommonCompilation && it.compilationName == "main" } - } else { - compilations - } -} - -private fun Project.isHmppEnabled(): Boolean { - // [KotlinCommonCompilation.isKlibCompilation] is internal, so we use this property instead. - // The property name might seem misleading, but it's set by KGP if HMPP is enabled: - // https://github.com/JetBrains/kotlin/blob/1.9.0/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/internal/hierarchicalStructureMigrationHandling.kt#L33 - return (this.findProperty("kotlin.mpp.enableGranularSourceSetsMetadata") as? String)?.toBoolean() - ?: false -} - -internal fun Project.allCompilationsOf( - sourceSet: KotlinSourceSet -): List { - return when (val kotlin = kotlin) { - is KotlinMultiplatformExtension -> allCompilationsOf(kotlin, sourceSet) - is KotlinSingleTargetExtension<*> -> allCompilationsOf(kotlin, sourceSet) - else -> emptyList() - } -} - -private fun allCompilationsOf( - kotlin: KotlinMultiplatformExtension, - sourceSet: KotlinSourceSet -): List { - val allCompilations = kotlin.targets.flatMap { target -> target.compilations } - return allCompilations.filter { compilation -> - sourceSet in compilation.allKotlinSourceSets || sourceSet == compilation.defaultSourceSet - } -} - -private fun allCompilationsOf( - kotlin: KotlinSingleTargetExtension<*>, - sourceSet: KotlinSourceSet -): List { - return kotlin.target.compilations.filter { compilation -> sourceSet in compilation.allKotlinSourceSets } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinSourceSetUtils.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinSourceSetUtils.kt deleted file mode 100644 index f5afd6cb..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/kotlinSourceSetUtils.kt +++ /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 org.jetbrains.dokka.gradle.kotlin - -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet - - -internal fun KotlinSourceSet.withAllDependentSourceSets(): Sequence { - return sequence { - yield(this@withAllDependentSourceSets) - for (dependentSourceSet in dependsOn) { - yieldAll(dependentSourceSet.withAllDependentSourceSets()) - } - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/platformOfSourceSet.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/platformOfSourceSet.kt deleted file mode 100644 index 8677d890..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/kotlin/platformOfSourceSet.kt +++ /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 org.jetbrains.dokka.gradle.kotlin - -import org.gradle.api.Project -import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet - -internal fun Project.platformOf(sourceSet: KotlinSourceSet): KotlinPlatformType { - val targetNames = allCompilationsOf(sourceSet).map { compilation -> compilation.target.platformType }.distinct() - return when (targetNames.size) { - 1 -> targetNames.single() - else -> KotlinPlatformType.common - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/sourceSetKotlinGistConfiguration.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/sourceSetKotlinGistConfiguration.kt deleted file mode 100644 index 8f21b9d3..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/sourceSetKotlinGistConfiguration.kt +++ /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. - */ - -package org.jetbrains.dokka.gradle - -import org.jetbrains.dokka.Platform -import org.jetbrains.dokka.gradle.kotlin.KotlinSourceSetGist -import org.jetbrains.dokka.gradle.kotlin.gistOf -import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet - -fun GradleDokkaSourceSetBuilder.configureWithKotlinSourceSet(sourceSet: KotlinSourceSet) { - configureWithKotlinSourceSetGist(project.gistOf(sourceSet)) -} - -internal fun GradleDokkaSourceSetBuilder.configureWithKotlinSourceSetGist(sourceSet: KotlinSourceSetGist) { - val dependentSourceSetIds = sourceSet.dependentSourceSetNames.map { sourceSetNames -> - sourceSetNames.map { sourceSetName -> DokkaSourceSetID(sourceSetName) } - } - - this.suppress.convention(sourceSet.isMain.map { !it }) - this.sourceRoots.from(sourceSet.sourceRoots) - this.classpath.from(sourceSet.classpath) - this.platform.convention(sourceSet.platform.map { Platform.fromString(it.name) }) - this.dependentSourceSets.convention(dependentSourceSetIds) - this.displayName.convention(sourceSet.platform.map { platform -> - sourceSet.name.substringBeforeLast( - delimiter = "Main", - missingDelimiterValue = platform.name - ) - }) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaLeafTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaLeafTask.kt deleted file mode 100644 index 03d40d8b..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaLeafTask.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. - */ - -@file:Suppress("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import org.gradle.api.NamedDomainObjectContainer -import org.gradle.api.internal.plugins.DslObject -import org.gradle.api.tasks.Internal -import org.gradle.api.tasks.Nested -import org.gradle.kotlin.dsl.container -import org.gradle.work.DisableCachingByDefault - -@DisableCachingByDefault(because = "Abstract super-class, not to be instantiated directly") -abstract class AbstractDokkaLeafTask : AbstractDokkaTask() { - - @get:Internal - val dokkaSourceSets: NamedDomainObjectContainer = - project.container(GradleDokkaSourceSetBuilder::class, gradleDokkaSourceSetBuilderFactory()).also { container -> - DslObject(this).extensions.add("dokkaSourceSets", container) - project.kotlinOrNull?.sourceSets?.all sourceSet@{ - container.register(name) { - configureWithKotlinSourceSet(this@sourceSet) - } - } - } - - /** - * Only contains source sets that are marked with `isDocumented`. - * Non documented source sets are not relevant for Gradle's UP-TO-DATE mechanism, as well - * as task dependency graph. - */ - @get:Nested - protected val unsuppressedSourceSets: List - get() = dokkaSourceSets - .toList() - .also(::checkSourceSetDependencies) - .filterNot { it.suppress.get() } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaParentTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaParentTask.kt deleted file mode 100644 index 62e98c30..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaParentTask.kt +++ /dev/null @@ -1,107 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import org.gradle.api.Project -import org.gradle.api.Task -import org.gradle.api.tasks.Internal -import org.gradle.api.tasks.Nested -import org.gradle.work.DisableCachingByDefault - -private const val DEPRECATION_MESSAGE = """ - It is an anti-pattern to declare cross-project dependencies as it leads to various build problems. - For this reason, this API wil be removed with the introduction of project isolation. - When it happens, we will provide a migration guide. In the meantime, you can keep using this API - if you have to, but please don't rely on it if possible. If you don't want to document a certain project, - don't apply the Dokka plugin for it, or disable individual project tasks using the Gradle API . -""" - -@Suppress("DEPRECATION") -@DisableCachingByDefault(because = "Abstract super-class, not to be instantiated directly") -abstract class AbstractDokkaParentTask : AbstractDokkaTask() { - - @get:Internal - internal var childDokkaTaskPaths: Set = emptySet() - private set - - @get:Nested - internal val childDokkaTasks: Set - get() = childDokkaTaskPaths - .mapNotNull { path -> project.tasks.findByPath(path) } - .map(::checkIsAbstractDokkaTask) - .toSet() - - /* By task reference */ - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun addChildTask(task: AbstractDokkaTask) { - childDokkaTaskPaths = childDokkaTaskPaths + task.path - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun removeChildTask(task: AbstractDokkaTask) { - childDokkaTaskPaths = childDokkaTaskPaths - task.path - } - - /* By path */ - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun addChildTask(path: String) { - childDokkaTaskPaths = childDokkaTaskPaths + project.absoluteProjectPath(path) - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun removeChildTask(path: String) { - childDokkaTaskPaths = childDokkaTaskPaths - project.absoluteProjectPath(path) - } - - /* By project reference and name */ - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun addChildTasks(projects: Iterable, childTasksName: String) { - projects.forEach { project -> - addChildTask(project.absoluteProjectPath(childTasksName)) - } - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun removeChildTasks(projects: Iterable, childTasksName: String) { - projects.forEach { project -> - removeChildTask(project.absoluteProjectPath(childTasksName)) - } - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun addSubprojectChildTasks(childTasksName: String) { - addChildTasks(project.subprojects, childTasksName) - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun removeSubprojectChildTasks(childTasksName: String) { - removeChildTasks(project.subprojects, childTasksName) - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun removeChildTasks(project: Project) { - childDokkaTaskPaths = childDokkaTaskPaths.filter { path -> - parsePath(path).parent != parsePath(project.path) - }.toSet() - } - - @Deprecated(message = DEPRECATION_MESSAGE, level = DeprecationLevel.WARNING) - fun removeChildTasks(projects: Iterable) { - projects.forEach { project -> removeChildTasks(project) } - } - - private fun checkIsAbstractDokkaTask(task: Task): AbstractDokkaTask { - if (task is AbstractDokkaTask) { - return task - } - throw IllegalArgumentException( - "Only tasks of type ${AbstractDokkaTask::class.java.name} can be added as child for " + - "${AbstractDokkaParentTask::class.java.name} tasks.\n" + - "Found task ${task.path} of type ${task::class.java.name} added to $path" - ) - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaTask.kt deleted file mode 100644 index 169ca050..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaTask.kt +++ /dev/null @@ -1,257 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import groovy.lang.Closure -import org.gradle.api.Action -import org.gradle.api.DefaultTask -import org.gradle.api.Task -import org.gradle.api.artifacts.Configuration -import org.gradle.api.file.DirectoryProperty -import org.gradle.api.plugins.JavaBasePlugin -import org.gradle.api.provider.ListProperty -import org.gradle.api.provider.MapProperty -import org.gradle.api.provider.Property -import org.gradle.api.tasks.* -import org.gradle.kotlin.dsl.listProperty -import org.gradle.kotlin.dsl.mapProperty -import org.gradle.kotlin.dsl.property -import org.gradle.work.DisableCachingByDefault -import org.jetbrains.dokka.* -import org.jetbrains.dokka.plugability.ConfigurableBlock -import org.jetbrains.dokka.plugability.DokkaPlugin -import java.util.concurrent.atomic.AtomicReference -import java.util.function.BiConsumer -import kotlin.reflect.full.createInstance -import kotlin.reflect.full.memberFunctions - -@DisableCachingByDefault(because = "Abstract super-class, not to be instantiated directly") -abstract class AbstractDokkaTask : DefaultTask() { - - /** - * Display name used to refer to the module. Used for ToC, navigation, logging, etc. - * - * If set for a single-project build or a MultiModule task, will be used as project name. - * - * Default is Gradle project name. - */ - @Input - val moduleName: Property = project.objects.property() - .convention(project.name) - - /** - * Module version. - * - * If set for a single-project build or a MultiModule task, will be used - * as project version by the versioning plugin. - * - * Default is Gradle project version. - */ - @Input - val moduleVersion: Property = project.objects.property() - .convention(project.provider { project.version.toString() }) - - /** - * Directory to which documentation will be generated, regardless of format. - * Can be set on per-task basis. - * - * Default is `project/buildDir/taskName.removePrefix("dokka").decapitalize()`, so - * for `dokkaHtmlMultiModule` task it will be `project/buildDir/htmlMultiModule` - */ - @get:OutputDirectory - abstract val outputDirectory: DirectoryProperty - - /** - * Configuration for Dokka plugins. This property is not expected to be used directly - if possible, use - * [pluginConfiguration] blocks (preferred) or [pluginsMapConfiguration] instead. - */ - @Input - val pluginsConfiguration: ListProperty = project.objects.listProperty() - - /** - * JSON configuration of Dokka plugins. - * - * Key is fully qualified Dokka plugin name, value is its configuration in JSON. - * - * Example: - * - * ```kotlin - * tasks.dokkaHtml { - * val dokkaBaseConfiguration = """ - * { - * "customAssets": ["${file("assets/my-image.png")}"], - * "customStyleSheets": ["${file("assets/my-styles.css")}"], - * "footerMessage": "(c) 2022 MyOrg" - * } - * """ - * pluginsMapConfiguration.set( - * mapOf("org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration) - * ) - * } - * ``` - */ - @Input - val pluginsMapConfiguration: MapProperty = project.objects.mapProperty() - - /** - * Whether to suppress obvious functions. - * - * A function is considered to be obvious if it is: - * - Inherited from `kotlin.Any`, `Kotlin.Enum`, `java.lang.Object` or `java.lang.Enum`, - * such as `equals`, `hashCode`, `toString`. - * - Synthetic (generated by the compiler) and does not have any documentation, such as - * `dataClass.componentN` or `dataClass.copy`. - * - * Default is `true` - */ - @Input - val suppressObviousFunctions: Property = project.objects.property() - .convention(DokkaDefaults.suppressObviousFunctions) - - /** - * Whether to suppress inherited members that aren't explicitly overridden in a given class. - * - * Note: this can suppress functions such as `equals`/`hashCode`/`toString`, but cannot suppress - * synthetic functions such as `dataClass.componentN` and `dataClass.copy`. Use [suppressObviousFunctions] - * for that. - * - * Default is `false`. - */ - @Input - val suppressInheritedMembers: Property = project.objects.property() - .convention(DokkaDefaults.suppressInheritedMembers) - - /** - * Whether to resolve remote files/links over network. - * - * This includes package-lists used for generating external documentation links: - * for instance, to make classes from standard library clickable. - * - * Setting this to `true` can significantly speed up build times in certain cases, - * but can also worsen documentation quality and user experience, for instance by - * not resolving some dependency's class/member links. - * - * When using offline mode, you can cache fetched files locally and provide them to - * Dokka as local paths. For instance, see [GradleExternalDocumentationLinkBuilder]. - * - * Default is `false`. - */ - @Input - val offlineMode: Property = project.objects.property() - .convention(DokkaDefaults.offlineMode) - - /** - * Whether to fail documentation generation if Dokka has emitted a warning or an error. - * Will wait until all errors and warnings have been emitted first. - * - * This setting works well with [GradleDokkaSourceSetBuilder.reportUndocumented] - * - * Default is `false`. - */ - @Input - val failOnWarning: Property = project.objects.property() - .convention(DokkaDefaults.failOnWarning) - - @get:Optional - @get:InputDirectory - @get:PathSensitive(PathSensitivity.RELATIVE) - abstract val cacheRoot: DirectoryProperty - - /** - * Type-safe configuration for a Dokka plugin. - * - * Note: this is available in Kotlin DSL only, if Dokka Gradle plugin was applied through `plugins` block - * and the configured plugin can be found on classpath, which may require adding a classpath dependency - * to `buildscript` block in case of external plugins. Some Dokka plugins, such as - * [org.jetbrains.dokka.base.DokkaBase], are on classpath by default. - * - * Example: - * - * ```kotlin - * import org.jetbrains.dokka.base.DokkaBase - * import org.jetbrains.dokka.base.DokkaBaseConfiguration - * - * tasks.dokkaHtml { - * pluginConfiguration { - * footerMessage = "Test" - * } - * } - * ``` - * - * @param P Plugin class that extends [DokkaPlugin] - * @param T Plugin configuration class that extends [ConfigurableBlock] - */ - inline fun pluginConfiguration(block: T.() -> Unit) { - val instance = T::class.createInstance().apply(block) - val pluginConfiguration = PluginConfigurationImpl( - fqPluginName = P::class.qualifiedName!!, - serializationFormat = DokkaConfiguration.SerializationFormat.JSON, - values = instance.toCompactJsonString() - ) - pluginsConfiguration.add(pluginConfiguration) - } - - @Classpath - val plugins: Configuration = project.maybeCreateDokkaPluginConfiguration(name) - - @Classpath - val runtime: Configuration = project.maybeCreateDokkaRuntimeConfiguration(name) - - final override fun doFirst(action: Action): Task = super.doFirst(action) - - final override fun doFirst(action: Closure<*>): Task = super.doFirst(action) - - @TaskAction - internal open fun generateDocumentation() { - DokkaBootstrap(runtime, DokkaBootstrapImpl::class).apply { - configure(buildDokkaConfiguration().toCompactJsonString(), createProxyLogger()) - val uncaughtExceptionHolder = AtomicReference() - /** - * Run in a new thread to avoid memory leaks that are related to ThreadLocal (that keeps `URLCLassLoader`) - * Currently, all `ThreadLocal`s leaking are in the compiler/IDE codebase. - */ - Thread { generate() }.apply { - setUncaughtExceptionHandler { _, throwable -> uncaughtExceptionHolder.set(throwable) } - start() - join() - } - uncaughtExceptionHolder.get()?.let { throw it } - } - } - - internal abstract fun buildDokkaConfiguration(): DokkaConfigurationImpl - - private fun createProxyLogger(): BiConsumer = BiConsumer { level, message -> - when (level) { - "debug" -> logger.debug(message) - "info" -> logger.info(message) - "progress" -> logger.lifecycle(message) - "warn" -> logger.warn(message) - "error" -> logger.error(message) - } - } - - init { - group = JavaBasePlugin.DOCUMENTATION_GROUP - // notCompatibleWithConfigurationCache was introduced in Gradle 7.4 - val containsNotCompatibleWithConfigurationCache = this::class.memberFunctions.any { it.name == "notCompatibleWithConfigurationCache" && it.parameters.firstOrNull()?.name == "reason" } - if (containsNotCompatibleWithConfigurationCache) { - super.notCompatibleWithConfigurationCache("Dokka tasks are not yet compatible with the Gradle configuration cache. See https://github.com/Kotlin/dokka/issues/1217") - } - } - - internal fun buildPluginsConfiguration(): List { - val manuallyConfigured = pluginsMapConfiguration.get().entries.map { entry -> - PluginConfigurationImpl( - entry.key, - DokkaConfiguration.SerializationFormat.JSON, - entry.value - ) - } - return pluginsConfiguration.get().mapNotNull { it as? PluginConfigurationImpl } + manuallyConfigured - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaCollectorTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaCollectorTask.kt deleted file mode 100644 index a45eec33..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaCollectorTask.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. - */ - -@file:Suppress("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import org.gradle.api.tasks.CacheableTask -import org.jetbrains.dokka.DokkaConfigurationImpl - -@CacheableTask -abstract class DokkaCollectorTask : AbstractDokkaParentTask() { - - override fun generateDocumentation() { - checkChildDokkaTasksIsNotEmpty() - super.generateDocumentation() - } - - override fun buildDokkaConfiguration(): DokkaConfigurationImpl { - val initialDokkaConfiguration = DokkaConfigurationImpl( - moduleName = moduleName.get(), - outputDir = outputDirectory.asFile.get(), - cacheRoot = cacheRoot.asFile.orNull, - failOnWarning = failOnWarning.get(), - offlineMode = offlineMode.get(), - pluginsClasspath = plugins.resolve().toList(), - pluginsConfiguration = buildPluginsConfiguration(), - suppressObviousFunctions = suppressObviousFunctions.get(), - suppressInheritedMembers = suppressInheritedMembers.get(), - ) - - val subprojectDokkaConfigurations = childDokkaTasks.map { dokkaTask -> dokkaTask.buildDokkaConfiguration() } - return subprojectDokkaConfigurations.fold(initialDokkaConfiguration) { acc, it: DokkaConfigurationImpl -> - acc.copy( - sourceSets = acc.sourceSets + it.sourceSets, - pluginsClasspath = acc.pluginsClasspath + it.pluginsClasspath - ) - } - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaMultiModuleTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaMultiModuleTask.kt deleted file mode 100644 index 2893704a..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaMultiModuleTask.kt +++ /dev/null @@ -1,115 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import org.gradle.api.file.ConfigurableFileCollection -import org.gradle.api.file.Directory -import org.gradle.api.internal.tasks.TaskDependencyInternal -import org.gradle.api.provider.Property -import org.gradle.api.provider.Provider -import org.gradle.api.tasks.* -import org.gradle.kotlin.dsl.property -import org.jetbrains.dokka.DokkaConfigurationImpl -import org.jetbrains.dokka.DokkaModuleDescriptionImpl -import java.io.File - -@Suppress("unused") // Shall provide source compatibility if possible -@Deprecated("Use 'DokkaMultiModuleTask' instead", ReplaceWith("DokkaMultiModuleTask"), DeprecationLevel.ERROR) -typealias DokkaMultimoduleTask = DokkaMultiModuleTask - -private typealias TaskPath = String - -@CacheableTask -abstract class DokkaMultiModuleTask : AbstractDokkaParentTask() { - - /** - * List of Markdown files that contain - * [module and package documentation](https://kotlinlang.org/docs/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 - - @Internal - val fileLayout: Property = project.objects.property() - .convention(DokkaMultiModuleFileLayout.CompactInParent) - - @get:InputFiles - @get:PathSensitive(PathSensitivity.RELATIVE) - internal abstract val sourceChildOutputDirectories: ConfigurableFileCollection - - @get:OutputDirectories - internal val targetChildOutputDirectories: Provider> = project.provider { - childDokkaTasks.map { task -> targetChildOutputDirectory(task).get() } - } - - @get:Input - internal val childDokkaTaskIncludes: Map> - get() = childDokkaTasks.filterIsInstance().associate { task -> - task.path to task.dokkaSourceSets.flatMap { it.includes }.toSet() - } - - // The method contains a reference to internal Gradle API that is nice not to use. - // There was an attempt to get rid of it, but it was not successful - // See: https://github.com/Kotlin/dokka/pull/2835 - @Internal - override fun getTaskDependencies(): TaskDependencyInternal = - super.getTaskDependencies() + childDokkaTasks - - - override fun generateDocumentation() { - checkChildDokkaTasksIsNotEmpty() - super.generateDocumentation() - } - - override fun buildDokkaConfiguration(): DokkaConfigurationImpl { - return DokkaConfigurationImpl( - moduleName = moduleName.get(), - moduleVersion = moduleVersion.getValidVersionOrNull(), - outputDir = outputDirectory.asFile.get(), - cacheRoot = cacheRoot.asFile.orNull, - pluginsConfiguration = buildPluginsConfiguration(), - failOnWarning = failOnWarning.get(), - offlineMode = offlineMode.get(), - pluginsClasspath = plugins.resolve().toList(), - modules = childDokkaTasks.map { dokkaTask -> - DokkaModuleDescriptionImpl( - name = dokkaTask.moduleName.get(), - relativePathToOutputDirectory = targetChildOutputDirectory(dokkaTask).get().asFile.relativeTo( - outputDirectory.asFile.get() - ), - includes = childDokkaTaskIncludes[dokkaTask.path].orEmpty(), - sourceOutputDirectory = dokkaTask.outputDirectory.asFile.get(), - ) - }, - includes = includes.toSet(), - ) - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTask.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTask.kt deleted file mode 100644 index 551ab62e..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTask.kt +++ /dev/null @@ -1,29 +0,0 @@ -/* - * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -@file:Suppress("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import org.gradle.api.tasks.* -import org.jetbrains.dokka.DokkaConfigurationImpl -import org.jetbrains.dokka.build - -@CacheableTask -abstract class DokkaTask : AbstractDokkaLeafTask() { - override fun buildDokkaConfiguration(): DokkaConfigurationImpl = - DokkaConfigurationImpl( - moduleName = moduleName.get(), - moduleVersion = moduleVersion.getValidVersionOrNull(), - outputDir = outputDirectory.asFile.get(), - cacheRoot = cacheRoot.asFile.orNull, - offlineMode = offlineMode.get(), - failOnWarning = failOnWarning.get(), - sourceSets = unsuppressedSourceSets.build(), - pluginsConfiguration = buildPluginsConfiguration(), - pluginsClasspath = plugins.resolve().toList(), - suppressObviousFunctions = suppressObviousFunctions.get(), - suppressInheritedMembers = suppressInheritedMembers.get(), - ) -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTaskPartial.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTaskPartial.kt deleted file mode 100644 index ae7d2066..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/DokkaTaskPartial.kt +++ /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("PackageDirectoryMismatch") - -package org.jetbrains.dokka.gradle - -import org.gradle.api.tasks.* -import org.jetbrains.dokka.DokkaConfigurationImpl -import org.jetbrains.dokka.build - -@CacheableTask -abstract class DokkaTaskPartial : AbstractDokkaLeafTask() { - - override fun buildDokkaConfiguration(): DokkaConfigurationImpl { - return DokkaConfigurationImpl( - moduleName = moduleName.get(), - moduleVersion = moduleVersion.orNull, - outputDir = outputDirectory.asFile.get(), - cacheRoot = cacheRoot.asFile.orNull, - offlineMode = offlineMode.get(), - failOnWarning = failOnWarning.get(), - sourceSets = unsuppressedSourceSets.build(), - pluginsConfiguration = buildPluginsConfiguration(), - pluginsClasspath = plugins.resolve().toList(), - delayTemplateSubstitution = true, - suppressObviousFunctions = suppressObviousFunctions.get(), - suppressInheritedMembers = suppressInheritedMembers.get(), - ) - } -} diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/utils.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/utils.kt deleted file mode 100644 index c17653aa..00000000 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/utils.kt +++ /dev/null @@ -1,49 +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.gradle - -import org.gradle.api.NamedDomainObjectContainer -import org.gradle.api.Project -import org.gradle.api.UnknownDomainObjectException -import org.gradle.util.Path -import org.gradle.kotlin.dsl.findByType -import org.gradle.kotlin.dsl.getByType -import org.jetbrains.kotlin.gradle.dsl.KotlinProjectExtension -import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType -import org.jetbrains.kotlin.gradle.plugin.KotlinTarget - - -/** Parse a Gradle path, e.g. `:project:subproject:taskName` */ -internal fun parsePath(path: String): Path = Path.path(path) - -internal val Project.kotlinOrNull: KotlinProjectExtension? - get() = try { - project.extensions.findByType() - } catch (e: Throwable) { - when (e) { - // if the user project doesn't have KGP applied, we won't be able to load the class; - // TypeNotPresentException is possible if it's loaded through reified generics. - is NoClassDefFoundError, is TypeNotPresentException, is ClassNotFoundException -> null - else -> throw e - } - } - -internal val Project.kotlin: KotlinProjectExtension - get() = project.extensions.getByType() - -internal fun Project.isAndroidProject() = try { - project.extensions.getByName("android") - true -} catch (e: UnknownDomainObjectException) { - false -} catch (e: ClassNotFoundException) { - false -} - -internal fun KotlinTarget.isAndroidTarget() = this.platformType == KotlinPlatformType.androidJvm - -internal fun NamedDomainObjectContainer.maybeCreate(name: String, configuration: T.() -> Unit): T { - return findByName(name) ?: create(name, configuration) -} diff --git a/runners/gradle-plugin/src/main/resources/META-INF/gradle-plugins/org.jetbrains.dokka.properties b/runners/gradle-plugin/src/main/resources/META-INF/gradle-plugins/org.jetbrains.dokka.properties deleted file mode 100644 index 7c26a3a1..00000000 --- a/runners/gradle-plugin/src/main/resources/META-INF/gradle-plugins/org.jetbrains.dokka.properties +++ /dev/null @@ -1,6 +0,0 @@ -# -# Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. -# - -implementation-class=org.jetbrains.dokka.gradle.DokkaPlugin -dokka-version= -- cgit