feat: enable Dokka v2 (#4056)

* feat: enable Dokka v2

* build: enable the kotest runner on multiplatform projects

* build: enforce consistency in the KMP subprojects

* ci: fix new task name

* ci: make sure to fail on broken links

* docs: link the home page

* ci: fix broken retry mechanism

* docs: fix links to KDoc

* docs: limit docs generation to subprojects until Kotlin/dokka#3979 is fixed

* docs: include both multi-module and overall documentation

* docs: only check the multimodule website

* docs: fix typo

* docs: revise replacements

.github/workflows/build-and-deploy.yml

@@ -120,8 +120,7 @@ jobs:
           # Once everything gets fixed, lychee could simply run on '/website/**/*.html'
           FILES="$(
             find build/website/ -name '*.html' |
-            grep -v /kdoc/ |
-            grep -v /javadoc/ |
+            grep -v /kdoc-modules/ |
             grep -v /tags/ |
             sed -e 's#^build##'
           )"
@@ -132,7 +131,7 @@ jobs:
           for attempt in $(seq 1 5); do
             echo "Attempt $attempt/5"
             docker run --rm -v "$(pwd)/build/website:/website" -e GITHUB_TOKEN lycheeverse/lychee:0.10.3 $(echo "$FILES") --exclude-file /website/lycheeignore -m 100 --accept 403,429,500,502,503 && break
-            if [ "$attempt" = "${{ inputs.retries-on-failure}}" ]; then false; else sleep 120; fi
+            if [ "$attempt" = "5" ]; then exit 1; else sleep 120; fi
           done
 
   # Create a staging repository on Central
@@ -214,7 +213,7 @@ jobs:
             ./gradlew\
               ${{ needs.ci-preparation.outputs.force-version }}\
               -PstagingRepositoryId=${{ needs.staging-repo.outputs.repo-id }}\
-              uploadKotlinOSSRH uploadKotlinMultiplatform uploadJvm uploadJs close --parallel || \
+              uploadOSSRH uploadKotlinMultiplatform uploadJvm uploadJs close --parallel || \
             #
             # Drop the staging repository if the build is not a release
             #

alchemist-api/build.gradle.kts

@@ -6,11 +6,16 @@
  * GNU General Public License, with a linking exception,
  * as described in the file LICENSE in the Alchemist distribution's top directory.
  */
+plugins {
+    id("dokka-convention")
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     api(libs.apache.commons.math3)
     api(libs.jool)
     api(libs.listset)
+    implementation(libs.kotlin.reflect)
 }
 
 publishing.publications {

alchemist-cognitive-agents/build.gradle.kts

@@ -10,13 +10,9 @@
 import Libs.alchemist
 import Libs.incarnation
 
-/*
- * Copyright (C) 2010-2019, Danilo Pianini and contributors listed in the main project's alchemist/build.gradle file.
- *
- * This file is part of Alchemist, and is distributed under the terms of the
- * GNU General Public License, with a linking exception,
- * as described in the file LICENSE in the Alchemist distribution's top directory.
- */
+plugins {
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     api(alchemist("api"))
@@ -26,6 +22,7 @@ dependencies {
     implementation(alchemist("physics"))
     implementation(libs.jgrapht.core)
     implementation(libs.konf)
+    implementation(libs.kotlin.reflect)
 
     testImplementation(alchemist("test"))
     testImplementation(incarnation("protelis"))

alchemist-engine/build.gradle.kts

@@ -6,17 +6,12 @@
  * GNU General Public License, with a linking exception,
  * as described in the file LICENSE in the Alchemist distribution's top directory.
  */
-
 import Libs.alchemist
 import Libs.incarnation
 
-/*
- * Copyright (C) 2010-2019, Danilo Pianini and contributors listed in the main project"s alchemist/build.gradle file.
- *
- * This file is part of Alchemist, and is distributed under the terms of the
- * GNU General Public License, with a linking exception,
- * as described in the file LICENSE in the Alchemist distribution"s top directory.
- */
+plugins {
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     api(alchemist("api"))

alchemist-euclidean-geometry/build.gradle.kts

@@ -10,13 +10,9 @@
 import Libs.alchemist
 import Libs.incarnation
 
-/*
- * Copyright (C) 2010-2019) Danilo Pianini and contributors listed in the main project"s alchemist/build.gradle file.
- *
- * This file is part of Alchemist) and is distributed under the terms of the
- * GNU General Public License) with a linking exception)
- * as described in the file LICENSE in the Alchemist distribution"s top directory.
- */
+plugins {
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     api(alchemist("api"))

alchemist-full/build.gradle.kts

@@ -25,6 +25,7 @@ import java.nio.charset.StandardCharsets
 import java.security.MessageDigest
 
 plugins {
+    id("kotlin-jvm-convention")
     application
     alias(libs.plugins.jpackage)
     alias(libs.plugins.shadowJar)
@@ -36,66 +37,22 @@ buildscript {
     }
 }
 
-kotlin {
-    jvm {
-        withJava()
-    }
-    sourceSets {
-        val commonMain by getting {
-            dependencies {
-                runtimeOnly(rootProject)
-                rootProject.subprojects.filterNot { it == project }.forEach {
-                    runtimeOnly(it)
-                }
-            }
-        }
-        val jvmMain by getting {
-            dependencies {
-                implementation(rootProject.libs.slf4j)
-            }
-        }
-        val commonTest by getting {
-            dependencies {
-                implementation(rootProject)
-                implementation(alchemist("loading"))
-                implementation(alchemist("physics"))
-                implementation(alchemist("test"))
-                implementation(rootProject.libs.kotest.assertions.core)
-                implementation(rootProject.libs.kotest.framework.engine)
-            }
-        }
-        val jvmTest by getting {
-            dependencies {
-                implementation(libs.kotest.runner)
-            }
-        }
+dependencies {
+    runtimeOnly(rootProject)
+    rootProject.subprojects.filterNot { it == project }.forEach {
+        runtimeOnly(it)
+        dokka(it)
     }
+    testImplementation(rootProject.libs.slf4j)
+    testImplementation(rootProject)
+    testImplementation(alchemist("loading"))
+    testImplementation(alchemist("physics"))
 }
 
-/**
- * @return a [FileCollection] containing the classpath of the multiplatform JVM projects.
- * If unspecified, the classpath is not correctly built when including common code from MP dependencies,
- * resulting in runtime errors.
- */
-private fun mpClasspath(): Provider<FileCollection> =
-    tasks
-        .named("compileKotlinJvm")
-        .map { it.outputs.files }
-        .flatMap { compileKtOutputs ->
-            configurations.named("jvmRuntimeClasspath").map { compileKtOutputs + it }
-        }
-
 application {
     mainClass.set("it.unibo.alchemist.Alchemist")
 }
 
-/**
- * Add the runtime classpath of the multiplatform JVM projects to the run task
- */
-tasks.run.configure {
-    classpath += mpClasspath().get()
-}
-
 // Shadow Jar
 tasks.withType<ShadowJar> {
     manifest {
@@ -119,7 +76,6 @@ tasks.withType<ShadowJar> {
         "gradlew.bat",
         "gradlew",
     )
-    from(mpClasspath())
     isZip64 = true
     mergeServiceFiles()
     destinationDirectory.set(rootProject.layout.buildDirectory.map { it.dir("shadow") })

alchemist-graphql-surrogates/build.gradle.kts

@@ -12,6 +12,7 @@ import com.expediagroup.graphql.plugin.gradle.tasks.AbstractGenerateClientTask
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
+    id("kotlin-jvm-convention")
     alias(libs.plugins.graphql.server)
 }
 

alchemist-graphql/build.gradle.kts

@@ -15,17 +15,22 @@ import com.expediagroup.graphql.plugin.gradle.tasks.AbstractGenerateClientTask
 import java.io.File.separator
 
 plugins {
+    id("kotlin-multiplatform-convention")
     alias(libs.plugins.kotest.multiplatform)
     alias(libs.plugins.kotlin.serialization)
     alias(libs.plugins.graphql.server)
     alias(libs.plugins.graphql.client)
 }
 
 kotlin {
-    jvm { withJava() }
-    js(IR) {
-        browser()
-        binaries.executable()
+    jvm()
+    js {
+        browser {
+            binaries.library()
+        }
+        nodejs {
+            binaries.library()
+        }
     }
     sourceSets {
         val commonMain by getting {
@@ -104,6 +109,7 @@ val surrogates = project(":${project.name}-surrogates")
 apollo {
     service(name) {
         generateKotlinModels.set(true)
+        generateSourcesDuringGradleSync.set(true)
         packageName.set("it.unibo.alchemist.boundary.graphql.client")
         schemaFiles.from(surrogates.layout.buildDirectory.file("schema.graphql"))
         srcDir("src/commonMain/resources/graphql")

alchemist-grid/build.gradle.kts

@@ -10,13 +10,9 @@
 import Libs.alchemist
 import Libs.incarnation
 
-/*
- * Copyright (C) 2010-2019, Danilo Pianini and contributors listed in the main project"s alchemist/build.gradle file.
- *
- * This file is part of Alchemist, and is distributed under the terms of the
- * GNU General Public License, with a linking exception,
- * as described in the file LICENSE in the Alchemist distribution"s top directory.
- */
+plugins {
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     api(libs.ignite.core)

alchemist-implementationbase/build.gradle.kts

@@ -6,16 +6,11 @@
  * GNU General Public License, with a linking exception,
  * as described in the file LICENSE in the Alchemist distribution's top directory.
  */
-
 import Libs.alchemist
 
-/*
- * Copyright (C) 2010-2019) Danilo Pianini and contributors listed in the main project"s alchemist/build.gradle file.
- *
- * This file is part of Alchemist) and is distributed under the terms of the
- * GNU General Public License) with a linking exception)
- * as described in the file LICENSE in the Alchemist distribution"s top directory.
- */
+plugins {
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     api(alchemist("api"))
@@ -24,6 +19,7 @@ dependencies {
     api(libs.apache.commons.lang3)
     api(libs.quadtree)
 
+    implementation(libs.kotlin.reflect)
     implementation(libs.boilerplate)
     implementation(libs.caffeine)
     implementation(libs.classgraph)

alchemist-incarnation-biochemistry/build.gradle.kts

@@ -10,23 +10,16 @@
 import Libs.alchemist
 import Util.allVerificationTasks
 import io.gitlab.arturbosch.detekt.Detekt
-import org.jetbrains.dokka.gradle.DokkaCollectorTask
-import org.jetbrains.dokka.gradle.DokkaTask
-import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import org.gradle.jvm.tasks.Jar
+import org.jetbrains.dokka.gradle.tasks.DokkaBaseTask
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 import org.jlleitschuh.gradle.ktlint.tasks.KtLintCheckTask
 import org.jlleitschuh.gradle.ktlint.tasks.KtLintFormatTask
 
-/*
- * Copyright (C) 2010-2019, Danilo Pianini and contributors listed in the main project"s alchemist/build.gradle file.
- *
- * This file is part of Alchemist, and is distributed under the terms of the
- * GNU General Public License, with a linking exception,
- * as described in the file LICENSE in the Alchemist distribution"s top directory.
- */
-
 plugins {
     antlr
+    id("kotlin-jvm-convention")
 }
 
 dependencies {
@@ -65,24 +58,22 @@ tasks.generateGrammarSource.configure {
     arguments = arguments + listOf("-visitor", "-package", destination, "-long-messages")
 }
 
-tasks.sourcesJar.configure { dependsOn(tasks.generateGrammarSource) }
-tasks.withType<KtLintFormatTask>().configureEach { dependsOn(tasks.generateGrammarSource) }
 tasks.generateTestGrammarSource {
     enabled = false
 }
 
+// Ensure that the grammar is generated before any task that needs it
 tasks {
-    val needGrammarGeneration =
-        listOf(
-            rootProject.tasks.withType<DokkaCollectorTask>(),
-            withType<Detekt>(),
-            withType<DokkaTask>(),
-            withType<DokkaTaskPartial>(),
-            withType<JavaCompile>(),
-            withType<KotlinCompile>(),
-            withType<KtLintCheckTask>(),
-        )
-    needGrammarGeneration.forEach {
+    listOf(
+        withType<Detekt>(),
+        withType<JavaCompile>(),
+        withType<KotlinCompile>(),
+        withType<KtLintCheckTask>(),
+        withType<KotlinCompilationTask<*>>(),
+        withType<DokkaBaseTask>(),
+        withType<Jar>(),
+        withType<KtLintFormatTask>(),
+    ).forEach {
         it.configureEach { dependsOn(generateGrammarSource) }
     }
 }

alchemist-incarnation-biochemistry/src/main/kotlin/it/unibo/alchemist/model/biochemistry/CellProperty.kt

@@ -97,7 +97,7 @@ interface CellProperty<P : Vector<P>> : NodeProperty<Double> {
     fun getAllNodesLinkWithJunction(): Set<Node<Double>> = junctions.values.flatMap { it.keys }.toSet()
 
     /**
-     * The total number of junctions presents in this [node].
+     * The total number of junctions in this [node].
      */
     val junctionsCount: Int
         get() = junctions.values.flatMap { it.values }.sum()

alchemist-incarnation-protelis/build.gradle.kts

@@ -1,3 +1,5 @@
+import Libs.alchemist
+
 /*
  * Copyright (C) 2010-2022, Danilo Pianini and contributors
  * listed, for each module, in the respective subproject's build.gradle.kts file.
@@ -7,15 +9,9 @@
  * as described in the file LICENSE in the Alchemist distribution's top directory.
  */
 
-import Libs.alchemist
-
-/*
- * Copyright (C) 2010-2019, Danilo Pianini and contributors listed in the main(project"s alchemist/build.gradle file.
- *
- * This file is part of Alchemist, and is distributed under the terms of the
- * GNU General Public License, with a linking exception,
- * as described in the file LICENSE in the Alchemist distribution"s top directory.
- */
+plugins {
+    id("kotlin-jvm-convention")
+}
 
 dependencies {
     // API