Minor refactoring of dokka versioning and publishing

.github/workflows/gh-pages.yml

@@ -28,7 +28,7 @@ jobs:
           java-version: 11
       - uses: gradle/gradle-build-action@v2
       - name: Get current dokka version
-        run: echo "DOKKA_VERSION=`./gradlew :properties | grep '^version:.*' | cut -d ' ' -f 2 | cut -d '-' -f 1`" >> $GITHUB_ENV
+        run: echo "DOKKA_VERSION=`./gradlew :properties | grep '^version:.*' | cut -d ' ' -f 2`" >> $GITHUB_ENV
         if: github.event_name == 'release' || steps.filter.outputs.docs_changed == 'true'
         working-directory: ./dokka
       - name: Build docs

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Building dokka
+## Building Dokka
 
 Dokka is built with Gradle. To build it, use `./gradlew build`.
 Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run dokka.
@@ -24,9 +24,18 @@ Here's how to import and configure Dokka in IntelliJ IDEA:
   message: "Error Loading Project: Cannot load 3 modules".  Open up the details
   of the error, and click "Remove Selected", as these module `.iml` files are
   safe to remove.
-
-In order to publish dokka locally use: `./gradlew publishToMavenLocal` and add `mavenLocal()` to repositories in the project you want to generate documentation for.
-This will allow you to run the latest version in your project from local maven repository. 
-Keep in mind that those builds are postfixed with `-SNAPSHOT`, eg. `1.4.0-SNAPSHOT`, so remember to update plugin version.
-Dokka version generated with this build is taken from `gradle.properties` file under `dokka_version_base` and is visible in logs while running `publishToMavenLocal` task.
 
+## Using/testing locally built Dokka
+
+If you want to use/test your locally built Dokka in a project, do the following:
+1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
+   For instance, you can set it to something like `1.6.10-my-fix-SNAPSHOT`.
+2. Publish it to maven local (`./gradlew publishToMavenLocal`)
+3. In the project you want to generate documentation for, add maven local as a plugin/dependency
+   repository (`mavenLocal()`)
+4. Update your dokka dependency to the version you've just published:
+```kotlin
+plugins {
+    id("org.jetbrains.dokka") version "1.6.10-my-fix-SNAPSHOT"
+}
+```

build.gradle.kts

@@ -80,7 +80,7 @@ nexusPublishing {
 }
 
 tasks.maybeCreate("dokkaPublish").run {
-    if (publicationChannels.any { it.isMavenRepository }) {
+    if (publicationChannels.any { it.isMavenRepository() }) {
         finalizedBy(tasks.named("closeAndReleaseSonatypeStagingRepository"))
     }
 }

buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt

@@ -5,30 +5,31 @@ package org.jetbrains
 import org.gradle.api.Project
 
 enum class DokkaPublicationChannel {
-    SpaceDokkaDev,
-    MavenCentral,
-    MavenCentralSnapshot;
-
-    val isSpaceRepository get() = this == SpaceDokkaDev
-
-    val isMavenRepository
-        get() = when (this) {
-            MavenCentral, MavenCentralSnapshot -> true
-            else -> false
-        }
+    SPACE_DOKKA_DEV,
+    MAVEN_CENTRAL,
+    MAVEN_CENTRAL_SNAPSHOT,
+    GRADLE_PLUGIN_PORTAL;
 
     val acceptedDokkaVersionTypes: List<DokkaVersionType>
         get() = when(this) {
-            MavenCentral -> listOf(DokkaVersionType.Release)
-            MavenCentralSnapshot -> listOf(DokkaVersionType.Snapshot)
-            SpaceDokkaDev -> listOf(DokkaVersionType.Release, DokkaVersionType.Dev, DokkaVersionType.MC, DokkaVersionType.Snapshot)
+            MAVEN_CENTRAL -> listOf(DokkaVersionType.RELEASE, DokkaVersionType.RC)
+            MAVEN_CENTRAL_SNAPSHOT -> listOf(DokkaVersionType.SNAPSHOT)
+            SPACE_DOKKA_DEV -> listOf(DokkaVersionType.RELEASE, DokkaVersionType.RC, DokkaVersionType.DEV, DokkaVersionType.SNAPSHOT)
+            GRADLE_PLUGIN_PORTAL -> listOf(DokkaVersionType.RELEASE, DokkaVersionType.RC)
         }
 
+    fun isSpaceRepository() = this == SPACE_DOKKA_DEV
+
+    fun isMavenRepository() =  this == MAVEN_CENTRAL || this == MAVEN_CENTRAL_SNAPSHOT
+
+    fun isGradlePluginPortal() = this == GRADLE_PLUGIN_PORTAL
+
     companion object {
         fun fromPropertyString(value: String): DokkaPublicationChannel = when (value) {
-            "space-dokka-dev" -> SpaceDokkaDev
-            "maven-central-release" -> MavenCentral
-            "maven-central-snapshot" -> MavenCentralSnapshot
+            "space-dokka-dev" -> SPACE_DOKKA_DEV
+            "maven-central-release" -> MAVEN_CENTRAL
+            "maven-central-snapshot" -> MAVEN_CENTRAL_SNAPSHOT
+            "gradle-plugin-portal" -> GRADLE_PLUGIN_PORTAL
             else -> throw IllegalArgumentException("Unknown dokka_publication_channel=$value")
         }
     }

buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt

@@ -4,26 +4,16 @@ import org.gradle.api.Project
 import org.gradle.kotlin.dsl.extra
 import org.gradle.kotlin.dsl.provideDelegate
 
+@Suppress("LocalVariableName") // property name with underscore as taken from gradle.properties
 fun Project.configureDokkaVersion(): String {
-    var dokka_version: String? by this.extra
-    if (dokka_version == null) {
-        val dokka_version_base: String by this
-        dokka_version = dokkaVersionFromBase(dokka_version_base)
-    }
+    val dokka_version: String? by this.extra
     return checkNotNull(dokka_version)
 }
 
-private fun dokkaVersionFromBase(baseVersion: String): String {
-    val buildNumber = System.getenv("BUILD_NUMBER")
-    val forceSnapshot = System.getenv("FORCE_SNAPSHOT") != null
-    if (forceSnapshot || buildNumber == null) {
-        return "$baseVersion-SNAPSHOT"
-    }
-    return "$baseVersion-$buildNumber"
-}
-
 val Project.dokkaVersion: String
     get() = configureDokkaVersion()
 
 val Project.dokkaVersionType: DokkaVersionType?
-    get() = DokkaVersionType.values().find { it.suffix.matches(dokkaVersion.substringAfter("-", "")) }
+    get() = DokkaVersionType.values().find {
+        it.suffix.matches(dokkaVersion.substringAfter("-", ""))
+    }

buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt

@@ -1,5 +1,8 @@
 package org.jetbrains
 
 enum class DokkaVersionType(val suffix: Regex) {
-    Release("^$".toRegex()), Snapshot("SNAPSHOT".toRegex()), Dev("dev-\\d+".toRegex()), MC("mc-\\d+".toRegex())
+    RELEASE("^$".toRegex()),
+    RC("RC\\d?".toRegex()),
+    SNAPSHOT("SNAPSHOT".toRegex()),
+    DEV("dev-\\d+".toRegex());
 }

buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt

@@ -3,6 +3,7 @@ package org.jetbrains
 import org.gradle.api.DefaultTask
 import org.gradle.api.GradleException
 import org.gradle.api.Project
+import org.gradle.api.artifacts.Dependency
 import org.gradle.api.artifacts.ProjectDependency
 import org.gradle.api.publish.PublishingExtension
 import org.gradle.api.publish.maven.MavenPublication
@@ -11,31 +12,34 @@ import org.gradle.kotlin.dsl.findByType
 
 open class ValidatePublications : DefaultTask() {
 
-    class UnpublishedProjectDependencyException(
-        project: Project, dependencyProject: Project
-    ) : GradleException(
-        "Published project ${project.path} cannot depend on unpublished project ${dependencyProject.path}"
-    )
-
+    init {
+        group = "verification"
+        project.tasks.named("check") {
+            dependsOn(this@ValidatePublications)
+        }
+    }
 
     @TaskAction
     fun validatePublicationConfiguration() {
-        @Suppress("LocalVariableName")
         project.subprojects.forEach { subProject ->
             val publishing = subProject.extensions.findByType<PublishingExtension>() ?: return@forEach
             publishing.publications
                 .filterIsInstance<MavenPublication>()
                 .filter { it.version == project.dokkaVersion }
-                .forEach { publication ->
+                .forEach { _ ->
                     checkProjectDependenciesArePublished(subProject)
                     subProject.assertPublicationVersion()
                 }
         }
     }
 
     private fun checkProjectDependenciesArePublished(project: Project) {
-        (project.configurations.findByName("implementation")?.allDependencies.orEmpty() +
-                project.configurations.findByName("api")?.allDependencies.orEmpty())
+        val implementationDependencies = project.findDependenciesByName("implementation")
+        val apiDependencies = project.findDependenciesByName("api")
+
+        val allDependencies = implementationDependencies + apiDependencies
+
+        allDependencies
             .filterIsInstance<ProjectDependency>()
             .forEach { projectDependency ->
                 val publishing = projectDependency.dependencyProject.extensions.findByType<PublishingExtension>()
@@ -52,23 +56,24 @@ open class ValidatePublications : DefaultTask() {
             }
     }
 
-    private fun Project.assertPublicationVersion() {
-        if (System.getenv("SKIP_VERSION_CHECK")?.contains("true", ignoreCase = true) == true)
-            return
+    private fun Project.findDependenciesByName(name: String): Set<Dependency> {
+        return configurations.findByName(name)?.allDependencies.orEmpty()
+    }
 
-        if (!publicationChannels.all { publicationChannel ->
-                publicationChannel.acceptedDokkaVersionTypes.any { acceptedVersionType ->
-                    acceptedVersionType == dokkaVersionType
-                }
-            }) {
+    private fun Project.assertPublicationVersion() {
+        val versionTypeMatchesPublicationChannels = publicationChannels.all { publicationChannel ->
+            publicationChannel.acceptedDokkaVersionTypes.any { acceptedVersionType ->
+                acceptedVersionType == dokkaVersionType
+            }
+        }
+        if (!versionTypeMatchesPublicationChannels) {
             throw AssertionError("Wrong version $dokkaVersion for configured publication channels $publicationChannels")
         }
     }
 
-    init {
-        group = "verification"
-        project.tasks.named("check") {
-            dependsOn(this@ValidatePublications)
-        }
-    }
+    private class UnpublishedProjectDependencyException(
+        project: Project, dependencyProject: Project
+    ): GradleException(
+        "Published project ${project.path} cannot depend on unpublished project ${dependencyProject.path}"
+    )
 }

buildSrc/src/main/kotlin/org/jetbrains/publication.kt

@@ -46,13 +46,13 @@ fun Project.registerDokkaArtifactPublication(publicationName: String, configure:
 }
 
 fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {
-    if (SpaceDokkaDev in this.publicationChannels) {
+    if (SPACE_DOKKA_DEV in this.publicationChannels) {
         configure<PublishingExtension> {
             repositories {
                 /* already registered */
-                findByName(SpaceDokkaDev.name)?.let { return@repositories }
+                findByName(SPACE_DOKKA_DEV.name)?.let { return@repositories }
                 maven {
-                    name = SpaceDokkaDev.name
+                    name = SPACE_DOKKA_DEV.name
                     url = URI.create("https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev")
                     credentials {
                         username = System.getenv("SPACE_PACKAGES_USER")
@@ -65,7 +65,7 @@ fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {
 
     whenEvaluated {
         tasks.withType<PublishToMavenRepository> {
-            if (this.repository.name == SpaceDokkaDev.name) {
+            if (this.repository.name == SPACE_DOKKA_DEV.name) {
                 this.isEnabled = this.isEnabled && publication.name in publications
                 if (!this.isEnabled) {
                     this.group = "disabled"
@@ -77,18 +77,22 @@ fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {
 
 fun Project.createDokkaPublishTaskIfNecessary() {
     tasks.maybeCreate("dokkaPublish").run {
-        if (publicationChannels.any { it.isSpaceRepository }) {
+        if (publicationChannels.any { it.isSpaceRepository() }) {
             dependsOn(tasks.named("publish"))
         }
 
-        if (publicationChannels.any { it.isMavenRepository }) {
+        if (publicationChannels.any { it.isMavenRepository() }) {
             dependsOn(tasks.named("publishToSonatype"))
         }
+
+        if (publicationChannels.any { it.isGradlePluginPortal() }) {
+            dependsOn(tasks.named("publishPlugins"))
+        }
     }
 }
 
 fun Project.configureSonatypePublicationIfNecessary(vararg publications: String) {
-    if (publicationChannels.any { it.isMavenRepository }) {
+    if (publicationChannels.any { it.isMavenRepository() }) {
         signPublicationsIfKeyPresent(*publications)
     }
 }

gradle.properties

@@ -1,6 +1,5 @@
 # Project Settings
-dokka_version_base=1.6.10
-dokka_publication_channels=maven-central-snapshot&space-dokka-dev
+dokka_version=1.6.20-SNAPSHOT
 dokka_integration_test_parallelism=2
 # Versions
 kotlin_version=1.6.20-RC