Contribute Dokkatoo (#3188)

72 files changed, 6941 insertions, 0 deletions

diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt
new file mode 100644
index 00000000..9d67471a
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt
@@ -0,0 +1,355 @@
+package org.jetbrains.dokka.dokkatoo
+
+import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes
+import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKATOO_BASE_ATTRIBUTE
+import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKATOO_CATEGORY_ATTRIBUTE
+import org.jetbrains.dokka.dokkatoo.distributions.DokkatooConfigurationAttributes.Companion.DOKKA_FORMAT_ATTRIBUTE
+import org.jetbrains.dokka.dokkatoo.dokka.parameters.DokkaSourceSetSpec
+import org.jetbrains.dokka.dokkatoo.dokka.parameters.KotlinPlatform
+import org.jetbrains.dokka.dokkatoo.dokka.parameters.VisibilityModifier
+import org.jetbrains.dokka.dokkatoo.internal.*
+import org.jetbrains.dokka.dokkatoo.tasks.DokkatooGenerateTask
+import org.jetbrains.dokka.dokkatoo.tasks.DokkatooPrepareModuleDescriptorTask
+import org.jetbrains.dokka.dokkatoo.tasks.DokkatooTask
+import java.io.File
+import javax.inject.Inject
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.json.Json
+import org.gradle.api.NamedDomainObjectContainer
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.artifacts.Configuration
+import org.gradle.api.file.ProjectLayout
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.provider.Property
+import org.gradle.api.provider.Provider
+import org.gradle.api.provider.ProviderFactory
+import org.gradle.api.tasks.TaskContainer
+import org.gradle.kotlin.dsl.*
+import org.gradle.language.base.plugins.LifecycleBasePlugin
+
+/**
+ * The base plugin for Dokkatoo. Sets up Dokkatoo and configures default values, but does not
+ * add any specific config (specifically, it does not create Dokka Publications).
+ */
+abstract class DokkatooBasePlugin
+@DokkatooInternalApi
+@Inject
+constructor(
+  private val providers: ProviderFactory,
+  private val layout: ProjectLayout,
+  private val objects: ObjectFactory,
+) : Plugin<Project> {
+
+  override fun apply(target: Project) {
+    // apply the lifecycle-base plugin so the clean task is available
+    target.pluginManager.apply(LifecycleBasePlugin::class)
+
+    val dokkatooExtension = createExtension(target)
+
+    target.tasks.createDokkaLifecycleTasks()
+
+    val configurationAttributes = objects.newInstance<DokkatooConfigurationAttributes>()
+
+    target.dependencies.attributesSchema {
+      attribute(DOKKATOO_BASE_ATTRIBUTE)
+      attribute(DOKKATOO_CATEGORY_ATTRIBUTE)
+      attribute(DOKKA_FORMAT_ATTRIBUTE)
+    }
+
+    target.configurations.register(dependencyContainerNames.dokkatoo) {
+      description = "Fetch all Dokkatoo files from all configurations in other subprojects"
+      asConsumer()
+      isVisible = false
+      attributes {
+        attribute(DOKKATOO_BASE_ATTRIBUTE, configurationAttributes.dokkatooBaseUsage)
+      }
+    }
+
+    configureDokkaPublicationsDefaults(dokkatooExtension)
+    dokkatooExtension.dokkatooSourceSets.configureDefaults(
+      sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault
+    )
+
+    target.tasks.withType<DokkatooGenerateTask>().configureEach {
+      cacheDirectory.convention(dokkatooExtension.dokkatooCacheDirectory)
+      workerDebugEnabled.convention(false)
+      workerLogFile.convention(temporaryDir.resolve("dokka-worker.log"))
+      workerJvmArgs.set(
+        listOf(
+          //"-XX:MaxMetaspaceSize=512m",
+          "-XX:+HeapDumpOnOutOfMemoryError",
+          "-XX:+AlwaysPreTouch", // https://github.com/gradle/gradle/issues/3093#issuecomment-387259298
+          //"-XX:StartFlightRecording=disk=true,name={path.drop(1).map { if (it.isLetterOrDigit()) it else '-' }.joinToString("")},dumponexit=true,duration=30s",
+          //"-XX:FlightRecorderOptions=repository=$baseDir/jfr,stackdepth=512",
+        )
+      )
+      dokkaConfigurationJsonFile.convention(temporaryDir.resolve("dokka-configuration.json"))
+    }
+
+    target.tasks.withType<DokkatooPrepareModuleDescriptorTask>().configureEach {
+      moduleName.convention(dokkatooExtension.moduleName)
+      includes.from(providers.provider { dokkatooExtension.dokkatooSourceSets.flatMap { it.includes } })
+      modulePath.convention(dokkatooExtension.modulePath)
+    }
+
+    target.tasks.withType<DokkatooGenerateTask>().configureEach {
+
+      publicationEnabled.convention(true)
+      onlyIf("publication must be enabled") { publicationEnabled.getOrElse(true) }
+
+      generator.dokkaSourceSets.addAllLater(
+        providers.provider {
+          // exclude suppressed source sets as early as possible, to avoid unnecessary dependency resolution
+          dokkatooExtension.dokkatooSourceSets.filterNot { it.suppress.get() }
+        }
+      )
+
+      generator.dokkaSourceSets.configureDefaults(
+        sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault
+      )
+    }
+
+    dokkatooExtension.dokkatooSourceSets.configureDefaults(
+      sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault
+    )
+  }
+
+  private fun createExtension(project: Project): DokkatooExtension {
+    val dokkatooExtension = project.extensions.create<DokkatooExtension>(EXTENSION_NAME).apply {
+      moduleName.convention(providers.provider { project.name })
+      moduleVersion.convention(providers.provider { project.version.toString() })
+      modulePath.convention(project.pathAsFilePath())
+      konanHome.convention(
+        providers
+          .provider {
+            // konanHome is set into in extraProperties:
+            // https://github.com/JetBrains/kotlin/blob/v1.9.0/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/native/KotlinNativeTargetPreset.kt#L35-L38
+            project.extensions.extraProperties.get("konanHome") as? String?
+          }
+          .map { File(it) }
+      )
+
+      sourceSetScopeDefault.convention(project.path)
+      dokkatooPublicationDirectory.convention(layout.buildDirectory.dir("dokka"))
+      dokkatooModuleDirectory.convention(layout.buildDirectory.dir("dokka-module"))
+      dokkatooConfigurationsDirectory.convention(layout.buildDirectory.dir("dokka-config"))
+    }
+
+    dokkatooExtension.versions {
+      jetbrainsDokka.convention(DokkatooConstants.DOKKA_VERSION)
+      jetbrainsMarkdown.convention("0.3.1")
+      freemarker.convention("2.3.31")
+      kotlinxHtml.convention("0.8.0")
+      kotlinxCoroutines.convention("1.6.4")
+    }
+
+    return dokkatooExtension
+  }
+
+  /** Set defaults in all [DokkatooExtension.dokkatooPublications]s */
+  private fun configureDokkaPublicationsDefaults(
+    dokkatooExtension: DokkatooExtension,
+  ) {
+    dokkatooExtension.dokkatooPublications.all {
+      enabled.convention(true)
+      cacheRoot.convention(dokkatooExtension.dokkatooCacheDirectory)
+      delayTemplateSubstitution.convention(false)
+      failOnWarning.convention(false)
+      finalizeCoroutines.convention(false)
+      moduleName.convention(dokkatooExtension.moduleName)
+      moduleVersion.convention(dokkatooExtension.moduleVersion)
+      offlineMode.convention(false)
+      outputDir.convention(dokkatooExtension.dokkatooPublicationDirectory)
+      suppressInheritedMembers.convention(false)
+      suppressObviousFunctions.convention(true)
+    }
+  }
+
+  /** Set conventions for all [DokkaSourceSetSpec] properties */
+  private fun NamedDomainObjectContainer<DokkaSourceSetSpec>.configureDefaults(
+    sourceSetScopeConvention: Property<String>,
+  ) {
+    configureEach dss@{
+      analysisPlatform.convention(KotlinPlatform.DEFAULT)
+      displayName.convention(
+        analysisPlatform.map { platform ->
+          // Match existing Dokka naming conventions. (This should probably be simplified!)
+          when {
+            // Multiplatform source sets (e.g. commonMain, jvmMain, macosMain)
+            name.endsWith("Main") -> name.substringBeforeLast("Main")
+
+            // indeterminate source sets should be named by the Kotlin platform
+            else                  -> platform.displayName
+          }
+        }
+      )
+      documentedVisibilities.convention(setOf(VisibilityModifier.PUBLIC))
+      jdkVersion.convention(8)
+
+      enableKotlinStdLibDocumentationLink.convention(true)
+      enableJdkDocumentationLink.convention(true)
+      enableAndroidDocumentationLink.convention(
+        analysisPlatform.map { it == KotlinPlatform.AndroidJVM }
+      )
+
+      reportUndocumented.convention(false)
+      skipDeprecated.convention(false)
+      skipEmptyPackages.convention(true)
+      sourceSetScope.convention(sourceSetScopeConvention)
+
+      // Manually added sourceSets should not be suppressed by default. dokkatooSourceSets that are
+      // automatically added by DokkatooKotlinAdapter will have a sensible value for suppress.
+      suppress.convention(false)
+
+      suppressGeneratedFiles.convention(true)
+
+      sourceLinks.configureEach {
+        localDirectory.convention(layout.projectDirectory)
+        remoteLineSuffix.convention("#L")
+      }
+
+      perPackageOptions.configureEach {
+        matchingRegex.convention(".*")
+        suppress.convention(false)
+        skipDeprecated.convention(false)
+        reportUndocumented.convention(false)
+      }
+
+      externalDocumentationLinks {
+        configureEach {
+          enabled.convention(true)
+          packageListUrl.convention(url.map { it.appendPath("package-list") })
+        }
+
+        maybeCreate("jdk") {
+          enabled.convention(this@dss.enableJdkDocumentationLink)
+          url(this@dss.jdkVersion.map { jdkVersion ->
+            when {
+              jdkVersion < 11 -> "https://docs.oracle.com/javase/${jdkVersion}/docs/api/"
+              else            -> "https://docs.oracle.com/en/java/javase/${jdkVersion}/docs/api/"
+            }
+          })
+          packageListUrl(this@dss.jdkVersion.map { jdkVersion ->
+            when {
+              jdkVersion < 11 -> "https://docs.oracle.com/javase/${jdkVersion}/docs/api/package-list"
+              else            -> "https://docs.oracle.com/en/java/javase/${jdkVersion}/docs/api/element-list"
+            }
+          })
+        }
+
+        maybeCreate("kotlinStdlib") {
+          enabled.convention(this@dss.enableKotlinStdLibDocumentationLink)
+          url("https://kotlinlang.org/api/latest/jvm/stdlib/")
+        }
+
+        maybeCreate("androidSdk") {
+          enabled.convention(this@dss.enableAndroidDocumentationLink)
+          url("https://developer.android.com/reference/kotlin/")
+        }
+
+        maybeCreate("androidX") {
+          enabled.convention(this@dss.enableAndroidDocumentationLink)
+          url("https://developer.android.com/reference/kotlin/")
+          packageListUrl("https://developer.android.com/reference/kotlin/androidx/package-list")
+        }