Refactor project structure and introduce composite builds

.github/workflows/preview-publish-ga.yml

@@ -27,7 +27,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.CoroutinesGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.CoroutinesGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/coroutines
       - name: Copy files to GitHub Actions Artifacts
@@ -56,7 +56,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.SerializationGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.SerializationGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/serialization
       - name: Copy files to GitHub Actions Artifacts
@@ -85,7 +85,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :integration-tests:maven:integrationTest --tests org.jetbrains.dokka.it.maven.BiojavaIntegrationTest --stacktrace
+          arguments: :dokka-integration-tests:maven:integrationTest --tests org.jetbrains.dokka.it.maven.BiojavaIntegrationTest --stacktrace
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/biojava
       - name: Copy files to GitHub Actions Artifacts

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

@@ -24,7 +24,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.CoroutinesGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.CoroutinesGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/coroutines
       - name: Configure AWS credentials for S3 access
@@ -34,7 +34,7 @@ jobs:
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           aws-region: eu-central-1
       - name: Copy files to dokka's S3 bucket
-        run: ./integration-tests/aws_sync.sh s3://${{ env.bucket-name }} coroutines ../coroutines
+        run: ./dokka-integration-tests/aws_sync.sh s3://${{ env.bucket-name }} coroutines ../coroutines
       - name: Print link
         run: echo https://dokka-snapshots.s3.eu-central-1.amazonaws.com/${{ env.branch-name }}/coroutines/${GITHUB_SHA::7}/index.html
 
@@ -55,7 +55,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.SerializationGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
+          arguments: :dokka-integration-tests:gradle:integrationTest --tests org.jetbrains.dokka.it.gradle.kotlin.SerializationGradleIntegrationTest --stacktrace "-Dorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=500m"
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/serialization
       - name: Configure AWS credentials for S3 access
@@ -65,7 +65,7 @@ jobs:
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           aws-region: eu-central-1
       - name: Copy files to dokka's S3 bucket
-        run: ./integration-tests/aws_sync.sh s3://${{ env.bucket-name }} serialization ../serialization
+        run: ./dokka-integration-tests/aws_sync.sh s3://${{ env.bucket-name }} serialization ../serialization
       - name: Print link
         run: echo https://dokka-snapshots.s3.eu-central-1.amazonaws.com/${{ env.branch-name }}/serialization/${GITHUB_SHA::7}/index.html
 
@@ -86,7 +86,7 @@ jobs:
         uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
-          arguments: :integration-tests:maven:integrationTest --tests org.jetbrains.dokka.it.maven.BiojavaIntegrationTest --stacktrace
+          arguments: :dokka-integration-tests:maven:integrationTest --tests org.jetbrains.dokka.it.maven.BiojavaIntegrationTest --stacktrace
         env:
           DOKKA_TEST_OUTPUT_PATH: /home/runner/work/dokka/biojava
       - name: Configure AWS credentials for S3 access
@@ -96,6 +96,6 @@ jobs:
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           aws-region: eu-central-1
       - name: Copy files to dokka's S3 bucket
-        run: ./integration-tests/aws_sync.sh s3://${{ env.bucket-name }} biojava ../biojava
+        run: ./dokka-integration-tests/aws_sync.sh s3://${{ env.bucket-name }} biojava ../biojava
       - name: Print link
         run: echo https://dokka-snapshots.s3.eu-central-1.amazonaws.com/${{ env.branch-name }}/biojava/${GITHUB_SHA::7}/index.html

.github/workflows/tests-smoke.yml

@@ -26,16 +26,17 @@ jobs:
       - uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
+          arguments: clean
       - name: Run tests under Windows
         if: matrix.os == 'windows-latest'
         # Running tests with the Gradle daemon on windows agents leads to some very strange
         # JVM crashes for some reason. Most likely a problem of Gradle/GitHub/Windows server
         run: >
-          ./gradlew clean test --stacktrace --no-daemon --no-parallel 
+          ./gradlew test --stacktrace --no-daemon --no-parallel 
           "-Dorg.gradle.jvmargs=-Xmx1g -XX:MaxMetaspaceSize=500m"
           "-Porg.jetbrains.dokka.javaToolchain.testLauncher=${{ env.JAVA_TEST_VERSION }}"
       - name: Run tests under Ubuntu
         if: matrix.os != 'windows-latest'
         run: >
-          ./gradlew clean test --stacktrace 
+          ./gradlew test --stacktrace 
           "-Porg.jetbrains.dokka.javaToolchain.testLauncher=${{ env.JAVA_TEST_VERSION }}"

.github/workflows/tests-thorough.yml

@@ -24,16 +24,17 @@ jobs:
       - uses: gradle/gradle-build-action@v2
         with:
           gradle-home-cache-cleanup: true
+          arguments: clean
       - name: Run tests under Windows
         if: matrix.os == 'windows-latest'
         # Running tests with the Gradle daemon on windows agents leads to some very strange
         # JVM crashes for some reason. Most likely a problem of Gradle/GitHub/Windows server
         run: >
-          ./gradlew clean test --stacktrace --no-daemon --no-parallel 
+          ./gradlew test --stacktrace --no-daemon --no-parallel 
           "-Dorg.gradle.jvmargs=-Xmx1g -XX:MaxMetaspaceSize=500m"
           "-Porg.jetbrains.dokka.javaToolchain.testLauncher=${{ matrix.javaVersion }}"
       - name: Run tests under Ubuntu/Macos
         if: matrix.os != 'windows-latest'
         run: >
-          ./gradlew clean test --stacktrace 
+          ./gradlew test --stacktrace 
           "-Porg.jetbrains.dokka.javaToolchain.testLauncher=${{ matrix.javaVersion }}"

.gitmodules

@@ -1,9 +1,9 @@
 [submodule "integration-tests/gradle/projects/coroutines/kotlinx-coroutines"]
-	path = integration-tests/gradle/projects/coroutines/kotlinx-coroutines
+	path = dokka-integration-tests/gradle/projects/coroutines/kotlinx-coroutines
 	url = https://github.com/Kotlin/kotlinx.coroutines
 [submodule "integration-tests/gradle/projects/serialization/kotlinx-serialization"]
-	path = integration-tests/gradle/projects/serialization/kotlinx-serialization
+	path = dokka-integration-tests/gradle/projects/serialization/kotlinx-serialization
 	url = https://github.com/Kotlin/kotlinx.serialization
 [submodule "integration-tests/maven/projects/biojava/biojava"]
-	path = integration-tests/maven/projects/biojava/biojava
+	path = dokka-integration-tests/maven/projects/biojava/biojava
 	url = https://github.com/biojava/biojava

build-logic/README.md

@@ -1,7 +1,18 @@
-# About build-logic Module
+# build-logic
 
-This module aims to share common build logic for whole projects, previously we were using [buildSrc](https://docs.gradle.org/7.6/userguide/organizing_gradle_projects.html#sec:build_sources),
-but for some reasons like "A change in buildSrc causes the whole project to become out-of-date", we are migrating to [composite builds](https://docs.gradle.org/7.6/userguide/composite_builds.html),
-which avoids the side effects of buildSrc.
+This project aims to share common build logic between subprojects.
 
-For more information, you can ref https://proandroiddev.com/stop-using-gradle-buildsrc-use-composite-builds-instead-3c38ac7a2ab3.
+In principle, this is similar to `buildSrc`, but this project utilizes [composite builds][1] to avoid various 
+[inconvenient side effects][2] of `buildSrc`.
+
+For more information, see [Sharing Build Logic between Subprojects][3]
+
+___
+
+Note: the filename pattern used for convention plugins is inspired by how Gradle configures its 
+own convention plugins; [example project here][4].
+
+[1]: https://docs.gradle.org/7.6/userguide/composite_builds.html
+[2]: https://proandroiddev.com/stop-using-gradle-buildsrc-use-composite-builds-instead-3c38ac7a2ab3
+[3]: https://docs.gradle.org/8.4/userguide/sharing_build_logic_between_subprojects.html
+[4]: https://github.com/gradle/gradle/tree/b165da7de15e70afb6cac564bf4aadf16aa157b3/build-logic/jvm/src/main/kotlin

build-logic/src/main/kotlin/org/jetbrains/conventions/base.gradle.kts → build-logic/src/main/kotlin/dokkabuild.base.gradle.kts

@@ -2,9 +2,7 @@
  * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-package org.jetbrains.conventions
-
-import org.jetbrains.DokkaBuildProperties
+import dokkabuild.DokkaBuildProperties
 
 /**
  * A convention plugin that sets up common config and sensible defaults for all subprojects.
@@ -16,12 +14,7 @@ plugins {
     base
 }
 
-val dokkaBuildProperties: DokkaBuildProperties = extensions.create(DokkaBuildProperties.EXTENSION_NAME)
-
-if (project != rootProject) {
-    project.group = rootProject.group
-    project.version = rootProject.version
-}
+extensions.create<DokkaBuildProperties>(DokkaBuildProperties.EXTENSION_NAME)
 
 tasks.withType<AbstractArchiveTask>().configureEach {
     // https://docs.gradle.org/current/userguide/working_with_files.html#sec:reproducible_archives

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

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    id("org.gradle.kotlin.kotlin-dsl")
+    id("dokkabuild.java")
+    kotlin("jvm")
+    id("dokkabuild.publish-gradle-plugin")
+}
+
+// org.gradle.kotlin.kotlin-dsl sets languageVersion and apiVersion to 1.8 by default starting from Gradle 8.
+// As we need to be compatible with previous Gradle versions, we need to set it back to 1.4.
+// Note: we should do it directly on tasks and not via top-level `kotlin.compilerOptions`
+//       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)
+
+        freeCompilerArgs.addAll(
+            // need 1.4 support, otherwise there might be problems
+            // with Gradle 6.x (it's bundling Kotlin 1.4)
+            "-Xsuppress-version-warnings",
+            "-Xjsr305=strict",
+            "-Xskip-metadata-version-check",
+        )
+    }
+}
+
+tasks.validatePlugins {
+    enableStricterValidation.set(true)
+}

build-logic/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts → build-logic/src/main/kotlin/dokkabuild.java.gradle.kts

@@ -2,25 +2,19 @@
  * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
-package org.jetbrains.conventions
-
 /**
- * Base configuration for Java projects.
- *
- * This convention plugin contains shared Java config for both the [KotlinJvmPlugin] convention plugin and
- * the Gradle Plugin subproject (which cannot have the `kotlin("jvm")` plugin applied).
+ * Base configuration for Java/JVM projects.
  */
 
 plugins {
-    id("org.jetbrains.conventions.base")
+    id("dokkabuild.base")
     java
 }
 
 java {
     toolchain {
         languageVersion.set(dokkaBuild.mainJavaVersion)
     }
-    withSourcesJar()
 }
 
 tasks.withType<Test>().configureEach {
@@ -40,3 +34,7 @@ tasks.withType<Test>().configureEach {
 dependencies {
     testImplementation(platform(libs.junit.bom))
 }
+
+tasks.processResources {
+    duplicatesStrategy = DuplicatesStrategy.FAIL
+}

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

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    id("dokkabuild.java")
+    kotlin("jvm")
+}
+
+val rootProjectsWithoutDependencyOnDokkaCore = listOf("dokka-integration-tests")
+
+kotlin {
+    explicitApi()
+    compilerOptions {
+        allWarningsAsErrors.set(true)
+        languageVersion.set(dokkaBuild.kotlinLanguageLevel)
+        apiVersion.set(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.
+        if (rootProject.name !in rootProjectsWithoutDependencyOnDokkaCore) {
+            optIn.addAll(
+                "kotlin.RequiresOptIn",
+                "org.jetbrains.dokka.InternalDokkaApi"
+            )
+        }
+
+        freeCompilerArgs.addAll(
+            // need 1.4 support, otherwise there might be problems
+            // with Gradle 6.x (it's bundling Kotlin 1.4)
+            "-Xsuppress-version-warnings",
+            "-Xjsr305=strict",
+            "-Xskip-metadata-version-check",
+        )
+    }
+}

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

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    `maven-publish`
+    signing
+}
+
+publishing {
+    repositories {
+        maven {
+            name = "mavenCentral"
+            url = uri("https://oss.sonatype.org/service/local/staging/deploy/maven2/")
+            credentials {
+                username = System.getenv("DOKKA_SONATYPE_USER")
+                password = System.getenv("DOKKA_SONATYPE_PASSWORD")
+            }
+        }
+        maven {
+            name = "spaceDev"
+            url = uri("https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev")
+            credentials {
+                username = System.getenv("DOKKA_SPACE_PACKAGES_USER")
+                password = System.getenv("DOKKA_SPACE_PACKAGES_SECRET")
+            }
+        }
+        maven {
+            name = "spaceTest"
+            url = uri("https://maven.pkg.jetbrains.space/kotlin/p/dokka/test")
+            credentials {
+                username = System.getenv("DOKKA_SPACE_PACKAGES_USER")
+                password = System.getenv("DOKKA_SPACE_PACKAGES_SECRET")
+            }
+        }
+        // Publish to a project-local Maven directory, for verification. To test, run:
+        // ./gradlew publishAllPublicationsToProjectLocalRepository
+        // and check $rootDir/build/maven-project-local
+        maven {
+            name = "projectLocal"
+            url = uri(rootProject.layout.buildDirectory.dir("maven-project-local"))
+        }
+    }
+
+    publications.withType<MavenPublication>().configureEach {
+        pom {
+            name.convention("Dokka ${project.name}")
+            description.convention("Dokka is an API documentation engine for Kotlin")
+            url.convention("https://github.com/Kotlin/dokka")
+
+            licenses {
+                license {
+                    name.convention("The Apache Software License, Version 2.0")
+                    url.convention("https://www.apache.org/licenses/LICENSE-2.0.txt")
+                    distribution.convention("repo")
+                }
+            }
+
+            developers {
+                developer {
+                    id.convention("JetBrains")
+                    name.convention("JetBrains Team")
+                    organization.convention("JetBrains")
+                    organizationUrl.convention("https://www.jetbrains.com")
+                }
+            }
+
+            scm {
+                connection.convention("scm:git:git://github.com/Kotlin/dokka.git")
+                url.convention("https://github.com/Kotlin/dokka")
+            }
+        }
+    }
+}
+
+signing {
+    useInMemoryPgpKeys(
+        System.getenv("DOKKA_SIGN_KEY_ID")?.takeIf(String::isNotBlank),
+        System.getenv("DOKKA_SIGN_KEY")?.takeIf(String::isNotBlank),
+        System.getenv("DOKKA_SIGN_KEY_PASSPHRASE")?.takeIf(String::isNotBlank),
+    )
+    sign(publishing.publications)
+    setRequired(provider { !project.version.toString().endsWith("-SNAPSHOT") })
+}
+
+// This is a hack for a Gradle 8 problem, see https://github.com/gradle/gradle/issues/26091
+//
+// Fails with the following error otherwise:
+// > Task ':runner-gradle-plugin-classic:publishDokkaPluginMarkerMavenPublicationToSpaceTestRepository' uses
+// > this output of task ':runner-gradle-plugin-classic:signPluginMavenPublication' without declaring an
+// > explicit or implicit dependency.
+tasks.withType<AbstractPublishToMaven>().configureEach {
+    val signingTasks = tasks.withType<Sign>()
+    mustRunAfter(signingTasks)
+}