diff options
Diffstat (limited to 'runners/gradle-plugin/src/main')
38 files changed, 0 insertions, 2521 deletions
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<Directory> - - /** - * 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<Directory> = 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<Directory> { - 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<Directory> = 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<Project> { - 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<DokkaTask>(name) { - configuration() - } - - if (project.parent != null) { - val partialName = "${name}Partial" - project.maybeCreateDokkaPluginConfiguration(partialName) - project.maybeCreateDokkaRuntimeConfiguration(partialName) - project.tasks.register<DokkaTaskPartial>(partialName) { - configuration() - } - } - - if (project.subprojects.isNotEmpty()) { - if (multiModuleTaskSupported) { - val multiModuleName = "${name}MultiModule" - project.maybeCreateDokkaPluginConfiguration(multiModuleName, setOf(allModulesPageAndTemplateProcessing)) - project.maybeCreateDokkaRuntimeConfiguration(multiModuleName) - - project.tasks.register<DokkaMultiModuleTask>(multiModuleName) { - @Suppress("DEPRECATION") - addSubprojectChildTasks("${name}Partial") - configuration() - description = "Runs all subprojects '$name' tasks and generates module navigation page" - } - - project.tasks.register<DefaultTask>("${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<DokkaCollectorTask>("${name}Collector") { - @Suppress("DEPRECATION") - addSubprojectChildTasks(name) - description = - "Generates documentation merging all subprojects '$name' tasks into one virtual module" - } - } - } - - private fun Project.configureEachAbstractDokkaTask() { - tasks.withType<AbstractDokkaTask>().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<DokkaMultiModuleTask>().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<String>.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<ExternalDocumentationLinkImpl> { - 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<File> { - 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<DokkaSourceSetID>, -) : DokkaConfigurationBuilder<DokkaSourceSetImpl> { - - @Input - val sourceSetID: DokkaSourceSetID = sourceSetIdFactory.create(name) - - /** - * Whether this source set should be skipped when generating documentation. - * - * Default is `false`. - */ - @Input - val suppress: Property<Boolean> = project.objects.property<Boolean>() - .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<String?> = 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<DokkaConfiguration.Visibility> = - project.objects.setProperty<DokkaConfiguration.Visibility>() - .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<DokkaSourceSetID> = project.objects.setProperty<DokkaSourceSetID>() - .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<Boolean> = project.objects.property<Boolean>() - .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<GradleSourceLinkBuilder> = project.objects.setProperty<GradleSourceLinkBuilder>() - .convention(emptySet()) - - /** - * Allows to customize documentation generation options on a per-package basis. - * - * @see GradlePackageOptionsBuilder for details - */ - @Nested - val perPackageOptions: ListProperty<GradlePackageOptionsBuilder> = - project.objects.listProperty<GradlePackageOptionsBuilder>() - .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<GradleExternalDocumentationLinkBuilder> = - project.objects.setProperty<GradleExternalDocumentationLinkBuilder>() - .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<Platform> = project.objects.property<Platform>() - .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<Boolean> = project.objects.property<Boolean>() - .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<Boolean> = project.objects.property<Boolean>() |