Merge branch 'refs/heads/master' into KT-64200/maven-jvm-test-suite

.github/workflows/preview-publish-web-s3.yml

@@ -63,6 +63,34 @@ jobs:
       - name: Print link
         run: echo https://dokka-snapshots.s3.eu-central-1.amazonaws.com/${{ env.branch-name }}/serialization/${GITHUB_SHA::7}/index.html
 
+  ui-showcase:
+    runs-on: ubuntu-latest
+    if: github.repository == 'Kotlin/dokka'
+    steps:
+      - name: Checkout dokka
+        uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 17
+      - uses: gradle/actions/setup-gradle@v3
+        with:
+          gradle-home-cache-cleanup: true
+      - name: Generate ui-showcase documentation
+        run: ./gradlew :dokka-integration-tests:gradle:testUiShowcaseProject
+        env:
+          DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/ui-showcase
+      - name: Configure AWS credentials for S3 access
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: eu-central-1
+      - name: Copy files to dokka's S3 bucket
+        run: ./dokka-integration-tests/aws_sync.sh s3://${{ env.bucket-name }} ui-showcase ../ui-showcase
+      - name: Print link
+        run: echo https://dokka-snapshots.s3.eu-central-1.amazonaws.com/${{ env.branch-name }}/ui-showcase/${GITHUB_SHA::7}/index.html
+
   biojava:
     runs-on: ubuntu-latest
     if: github.repository == 'Kotlin/dokka'

.github/workflows/tests-smoke.yml

@@ -17,6 +17,11 @@ jobs:
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
+      - name: Set longpaths support for Windows
+        if: matrix.os == 'windows-latest'
+        # Avoid failing tests on Windows with "cannot create directory at X. Filename too long"
+        # This command will fail if run on a Linux build agent with "could not lock config file: Permission denied"
+        run: git config --system core.longpaths true
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:

.github/workflows/tests-thorough.yml

@@ -15,6 +15,11 @@ jobs:
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
+      - name: Set longpaths support for Windows
+        if: matrix.os == 'windows-latest'
+        # Avoid failing tests on Windows with "cannot create directory at X. Filename too long"
+        # This command will fail if run on a Linux build agent with "could not lock config file: Permission denied"
+        run: git config --system core.longpaths true
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:

build-logic/settings.gradle.kts

@@ -6,14 +6,14 @@ rootProject.name = "build-logic"
 
 pluginManagement {
     repositories {
-        gradlePluginPortal()
         mavenCentral()
+        gradlePluginPortal()
     }
     includeBuild("../build-settings-logic")
 }
 
-@Suppress("UnstableApiUsage")
 dependencyResolutionManagement {
+    @Suppress("UnstableApiUsage")
     repositories {
         mavenCentral()
         google()

build-logic/src/main/kotlin/dokkabuild.gradle-plugin.gradle.kts

@@ -17,8 +17,8 @@ plugins {
 //       because `kotlin-dsl plugin` declares them on task level, and so top-level config is overridden
 tasks.withType<KotlinCompile>().configureEach {
     compilerOptions {
-        languageVersion.set(dokkaBuild.kotlinLanguageLevel)
-        apiVersion.set(dokkaBuild.kotlinLanguageLevel)
+        languageVersion = dokkaBuild.kotlinLanguageLevel
+        apiVersion = dokkaBuild.kotlinLanguageLevel
 
         freeCompilerArgs.addAll(
             // need 1.4 support, otherwise there might be problems
@@ -31,5 +31,5 @@ tasks.withType<KotlinCompile>().configureEach {
 }
 
 tasks.validatePlugins {
-    enableStricterValidation.set(true)
+    enableStricterValidation = true
 }

build-logic/src/main/kotlin/dokkabuild.java.gradle.kts

@@ -13,7 +13,7 @@ plugins {
 
 java {
     toolchain {
-        languageVersion.set(dokkaBuild.mainJavaVersion)
+        languageVersion = dokkaBuild.mainJavaVersion
     }
 }
 
@@ -26,9 +26,9 @@ tasks.withType<Test>().configureEach {
         (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1
     }
 
-    javaLauncher.set(javaToolchains.launcherFor {
-        languageVersion.set(dokkaBuild.testJavaLauncherVersion)
-    })
+    javaLauncher = javaToolchains.launcherFor {
+        languageVersion = dokkaBuild.testJavaLauncherVersion
+    }
 }
 
 dependencies {

build-logic/src/main/kotlin/dokkabuild.kotlin-jvm.gradle.kts

@@ -12,9 +12,9 @@ val rootProjectsWithoutDependencyOnDokkaCore = listOf("dokka-integration-tests")
 kotlin {
     explicitApi()
     compilerOptions {
-        allWarningsAsErrors.set(true)
-        languageVersion.set(dokkaBuild.kotlinLanguageLevel)
-        apiVersion.set(dokkaBuild.kotlinLanguageLevel)
+        allWarningsAsErrors = true
+        languageVersion = dokkaBuild.kotlinLanguageLevel
+        apiVersion = dokkaBuild.kotlinLanguageLevel
 
         // These projects know nothing about the `@InternalDokkaApi` annotation, so the Kotlin compiler
         // will complain about an unresolved opt-in requirement marker and fail the build if it's not excluded.

build-logic/src/main/kotlin/dokkabuild.publish-base.gradle.kts

@@ -1,9 +1,9 @@
-import java.net.URI
-
 /*
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+import java.net.URI
+
 plugins {
     id("dokkabuild.base")
     `maven-publish`
@@ -93,7 +93,9 @@ signing {
         System.getenv("DOKKA_SIGN_KEY_PASSPHRASE")?.takeIf(String::isNotBlank),
     )
     sign(publishing.publications)
-    setRequired(provider { !project.version.toString().endsWith("-SNAPSHOT") })
+    // no signing should be required for locally published artifacts,
+    // as they are used for manual testing and running integration tests only
+    setRequired(provider { gradle.taskGraph.allTasks.any { it is PublishToMavenRepository } })
 }
 
 // This is a hack for a Gradle 8 problem, see https://github.com/gradle/gradle/issues/26091
@@ -106,10 +108,3 @@ tasks.withType<AbstractPublishToMaven>().configureEach {
     val signingTasks = tasks.withType<Sign>()
     mustRunAfter(signingTasks)
 }
-
-tasks.withType<PublishToMavenRepository>().configureEach {
-    // Configuration Cache allows tasks to run in parallel. Maven repositories (especially Maven Central)
-    // can't cope with parallel uploads, and might drop or split publications.
-    // As a workaround, disable Configuration Cache whenever publishing to remote Maven repos.
-    notCompatibleWithConfigurationCache("Prevent parallel publishing tasks")
-}

build-logic/src/main/kotlin/dokkabuild.publish-gradle-plugin.gradle.kts

@@ -11,8 +11,8 @@ plugins {
 
 @Suppress("UnstableApiUsage")
 gradlePlugin {
-    website.set("https://kotl.in/dokka")
-    vcsUrl.set("https://github.com/kotlin/dokka.git")
+    website = "https://kotl.in/dokka"
+    vcsUrl = "https://github.com/kotlin/dokka.git"
 }
 
 // com.gradle.plugin-publish configures publication in afterEvaluate block

build-logic/src/main/kotlin/dokkabuild.publish-shadow.gradle.kts

@@ -17,9 +17,9 @@ java {
 
 tasks.shadowJar {
     // separate directory because otherwise Gradle complains about multiple tasks writing into the same file
-    destinationDirectory.set(project.layout.buildDirectory.dir("shadowLibs"))
+    destinationDirectory = project.layout.buildDirectory.dir("shadowLibs")
     // removes the `-all` classifier from the artifact name
-    archiveClassifier.set("")
+    archiveClassifier = ""
 }
 
 publishing.publications.register<MavenPublication>(PublicationName.JVM) {

build-settings-logic/settings.gradle.kts

@@ -15,7 +15,7 @@ pluginManagement {
 
 @Suppress("UnstableApiUsage")
 dependencyResolutionManagement {
-    repositoriesMode.set(PREFER_SETTINGS)
+    repositoriesMode = PREFER_SETTINGS
     repositories {
         mavenCentral()
         gradlePluginPortal()

docs/topics/dokka-introduction.md

@@ -13,7 +13,7 @@ Here are some libraries that use Dokka for their API reference documentation:
 
 * [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/)
 * [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
-* [Hexagon](https://hexagonkt.com/api/index.html)
+* [Hexagon](https://hexagontk.com/api/)
 * [Ktor](https://api.ktor.io/)
 * [OkHttp](https://square.github.io/okhttp/5.x/okhttp/okhttp3/)
 

docs/topics/formats/dokka-markdown.md

@@ -8,7 +8,7 @@
 Dokka is able to generate documentation in [GitHub Flavored](#gfm) and [Jekyll](#jekyll) compatible Markdown.
 
 These formats give you more freedom in terms of hosting documentation as the output can be embedded right into your 
-documentation website. For example, see [OkHttp's API reference](https://square.github.io/okhttp/4.x/okhttp/okhttp3/)
+documentation website. For example, see [OkHttp's API reference](https://square.github.io/okhttp/5.x/okhttp/okhttp3/)
 pages.
 
 Markdown output formats are implemented as [Dokka plugins](dokka-plugins.md), maintained by the Dokka team, and 

dokka-integration-tests/gradle.properties

@@ -5,7 +5,7 @@
 # while integration test projects aren't published,
 # the version here should be in sync with other versions,
 # because it's used to resolve dependencies
-version=2.0.0-SNAPSHOT
+version=2.0.20-SNAPSHOT
 
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8

dokka-integration-tests/gradle/build.gradle.kts

@@ -182,6 +182,7 @@ testing {
                 }
             }
         }
+        registerTestProjectSuite("testUiShowcaseProject", "ui-showcase")
     }
 }
 

dokka-integration-tests/gradle/projects/it-android-0/settings.gradle.kts

@@ -2,7 +2,5 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("LocalVariableName", "UnstableApiUsage")
-
 apply(from = "template.settings.gradle.kts")
 rootProject.name = "it-android-0"

dokka-integration-tests/gradle/projects/it-basic-groovy/settings.gradle.kts

@@ -2,7 +2,5 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("LocalVariableName", "UnstableApiUsage")
-
 apply(from = "template.settings.gradle.kts")
 rootProject.name = "it-basic-groovy"

dokka-integration-tests/gradle/projects/it-basic/build.gradle.kts

@@ -20,7 +20,7 @@ buildscript {
     }
 }
 
-version = "2.0.0-SNAPSHOT"
+version = "2.0.20-SNAPSHOT"
 
 dependencies {
     testImplementation(kotlin("test-junit"))

dokka-integration-tests/gradle/projects/it-basic/settings.gradle.kts

@@ -2,7 +2,5 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("LocalVariableName", "UnstableApiUsage")
-
 apply(from = "template.settings.gradle.kts")
 rootProject.name = "it-basic"

dokka-integration-tests/gradle/projects/it-configuration/build.gradle.kts

@@ -16,7 +16,7 @@ buildscript {
     }
 }
 
-version = "2.0.0-SNAPSHOT"
+version = "2.0.20-SNAPSHOT"
 
 tasks.withType<DokkaTask> {
     moduleName.set("Configuration Test Project")

dokka-integration-tests/gradle/projects/it-js-ir-0/settings.gradle.kts

@@ -2,7 +2,5 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("LocalVariableName", "UnstableApiUsage")
-
 apply(from = "template.settings.gradle.kts")
 rootProject.name = "it-js-ir-0"

dokka-integration-tests/gradle/projects/it-sequential-tasks-execution-stress/settings.gradle.kts

@@ -2,7 +2,5 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("LocalVariableName", "UnstableApiUsage")
-
 apply(from = "template.settings.gradle.kts")
 rootProject.name = "it-sequential-tasks-execution-stress"

dokka-integration-tests/gradle/projects/template.settings.gradle.kts

@@ -2,8 +2,6 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-@file:Suppress("LocalVariableName", "UnstableApiUsage")
-
 pluginManagement {
     val dokka_it_kotlin_version: String by settings
     val dokka_it_dokka_version: String by settings

dokka-integration-tests/ui/test-project/README.md → dokka-integration-tests/gradle/projects/ui-showcase/README.md

@@ -5,16 +5,9 @@ This is a Dokka test project for UI e2e tests.
 The goal is to have as much variety of UI elements in one project as possible, so that during refactorings
 we can compare the outputs between different versions of Dokka and make sure we didn't break any corner cases.
 
-## How To
-
-### Change Dokka version
-
-The used Dokka version can be changed in [gradle/libs.versions.toml](gradle/libs.versions.toml).
-
-Currently, this project works with release, `-dev`, `-test` and `-SNAPSHOT` versions.
-
-### Run
+### Run from root of the project
 
 ```bash
-./gradlew dokkaHtmlMultiModule
+export DOKKA_TEST_OUTPUT_PATH="build/ui-showcase-result"
+./gradlew :dokka-integration-tests:gradle:testUiShowcaseProject
 ```

dokka-integration-tests/gradle/projects/ui-showcase/build-logic/build.gradle.kts

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    `kotlin-dsl`
+}
+
+val dokka_it_kotlin_version: String by project
+val dokka_it_dokka_version: String by project
+
+dependencies {
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:$dokka_it_dokka_version")
+    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:$dokka_it_kotlin_version")
+}

dokka-integration-tests/gradle/projects/ui-showcase/build-logic/settings.gradle.kts

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+apply(from = "../template.settings.gradle.kts")
+rootProject.name = "build-logic"

dokka-integration-tests/ui/test-project/build-logic/src/main/kotlin/uitest.dokka.gradle.kts → dokka-integration-tests/gradle/projects/ui-showcase/build-logic/src/main/kotlin/uitest.dokka-kmp.gradle.kts

@@ -1,20 +1,23 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
 import org.intellij.lang.annotations.Language
 import org.jetbrains.dokka.gradle.AbstractDokkaTask
 
 plugins {
-    id("uitest.base")
-    id("org.jetbrains.dokka")
+    id("uitest.dokka")
 }
 
-
 tasks.withType<AbstractDokkaTask>().configureEach {
     @Language("JSON")
     val dokkaBaseConfiguration = """
     {
-      "footerMessage": "(c) 2024 My footer message",
-      "homepageLink": "https://github.com/Kotlin/dokka/tree/master/dokka-integration-tests/ui/test-project"
+      "footerMessage": "(c) 2024 My custom footer message",
+      "homepageLink": "https://github.com/Kotlin/dokka/tree/master/dokka-integration-tests/gradle/projects/ui-showcase"
     }
     """.trimIndent()
+
     pluginsMapConfiguration.set(
         mapOf(
             // fully qualified plugin name to json configuration