Add task to generate Kotlinlang reference

Based on the template from
https://github.com/JetBrains/kotlin-web-site/tree/master/dokka-templates.
Template itself is updated frequently and should be added by CI
configuration.

Generated reference has versioning support. Older generated references
should put into:
<project_dir>/<build_dir>/dokka/kotlinlangDocumentationOld

^KT-55520 Fixed

buildSrc/src/main/kotlin/GradleCommon.kt

@@ -589,7 +589,8 @@ fun Project.addBomCheckTask() {
 }
 
 fun Project.configureDokkaPublication(
-    shouldLinkGradleApi: Boolean = false
+    shouldLinkGradleApi: Boolean = false,
+    configurePublishingToKotlinlang: Boolean = false,
 ) {
     if (!kotlinBuildProperties.publishGradlePluginsJavadoc) return
 
@@ -639,6 +640,52 @@ fun Project.configureDokkaPublication(
                 from(dokkaTask.flatMap { it.outputDirectory })
             }
         }
+
+        if (configurePublishingToKotlinlang) {
+            val latestVariant = GradlePluginVariant.values().last()
+            val olderVersionsDir = layout.buildDirectory.dir("dokka/kotlinlangDocumentationOld")
+
+            project.dependencies {
+                // Version is required due to https://github.com/Kotlin/dokka/issues/2812
+                "dokkaPlugin"("org.jetbrains.dokka:versioning-plugin:1.7.20")
+            }
+
+            tasks.register<DokkaTask>("dokkaKotlinlangDocumentation") {
+                description = "Generates documentation reference for Kotlinlang"
+
+                dokkaSourceSets {
+                    pluginsMapConfiguration.put(
+                        "org.jetbrains.dokka.base.DokkaBase",
+                        "{ \"templatesDir\": \"${layout.projectDirectory.dir("dokka-template")}\" }"
+                    )
+                    pluginsMapConfiguration.put(
+                        "org.jetbrains.dokka.versioning.VersioningPlugin",
+                        olderVersionsDir.map { olderVersionsDir ->
+                            "{ \"version\":\"$version\", \"olderVersionsDir\":\"${olderVersionsDir.asFile}\" }"
+                        }
+                    )
+
+                    named(commonSourceSet.name) {
+                        suppress.set(false)
+                        jdkVersion.set(8)
+                    }
+
+                    named(latestVariant.sourceSetName) {
+                        dependsOn(commonSourceSet)
+                        suppress.set(false)
+                        jdkVersion.set(8)
+
+                        if (shouldLinkGradleApi) {
+                            externalDocumentationLink {
+                                url.set(URL(latestVariant.gradleApiJavadocUrl))
+
+                                addWorkaroundForElementList(latestVariant)
+                            }
+                        }
+                    }
+                }
+            }
+        }
     }
 }
 

gradle/verification-metadata.xml

@@ -6767,6 +6767,18 @@
             <sha256 value="8b2d5db5b8789dff999507269b0c1b1a5812944b559fa5bdb9d1eb867b0b7fd2" origin="Generated by Gradle"/>
          </artifact>
       </component>
+      <component group="org.jetbrains.dokka" name="templating-plugin" version="1.7.20">
+         <artifact name="templating-plugin-1.7.20.jar">
+            <md5 value="e1e45fd22f223100309d1f1995a6adbb" origin="Generated by Gradle"/>
+            <sha256 value="72fd69ad713e2563bc4f4463555041cfc0da2e77951be2218f40f42895ce2f3e" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
+      <component group="org.jetbrains.dokka" name="versioning-plugin" version="1.7.20">
+         <artifact name="versioning-plugin-1.7.20.jar">
+            <md5 value="0159dc1164c29429581b162443d76bca" origin="Generated by Gradle"/>
+            <sha256 value="e388a725bc3bd21535245b083a231aaebe346756301913a6ba61b6902cd844a1" origin="Generated by Gradle"/>
+         </artifact>
+      </component>
       <component group="org.jetbrains.intellij.deps" name="asm-all" version="8.0.1">
          <artifact name="asm-all-8.0.1-sources.jar">
             <md5 value="720adbce2a64c91af5ee80112e2ecea7" origin="Generated by Gradle"/>

libraries/tools/kotlin-gradle-plugin-api/build.gradle.kts

@@ -5,7 +5,8 @@ plugins {
 }
 
 configureDokkaPublication(
-    shouldLinkGradleApi = true
+    shouldLinkGradleApi = true,
+    configurePublishingToKotlinlang = true,
 )
 
 dependencies {

libraries/tools/kotlin-gradle-plugin-api/dokka-template/ReadMe.md

@@ -0,0 +1,13 @@
+# Dokka's template customization
+
+To provide unified navigation for all parts of [kotlinlang.org](https://kotlinlang.org/),
+the Kotlin Website Team uses this directory to place custom templates in this folder
+during the website build time on TeamCity.
+
+It is not practical to place these templates in the kotlinx-datetime repository because they change from time to time
+and aren't related to the plugin's release cycle.
+
+The folder is defined as a source for custom templates by the templatesDir property through Dokka's plugin configuration.
+
+[Here](https://kotlin.github.io/dokka/1.7.20/user_guide/output-formats/html/#custom-html-pages), you can
+find more about the customization of Dokka's HTML output.