diff options
| -rw-r--r-- | .github/workflows/gh-pages.yml | 2 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 21 | ||||
| -rw-r--r-- | build.gradle.kts | 2 | ||||
| -rw-r--r-- | buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt | 35 | ||||
| -rw-r--r-- | buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt | 20 | ||||
| -rw-r--r-- | buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt | 5 | ||||
| -rw-r--r-- | buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt | 53 | ||||
| -rw-r--r-- | buildSrc/src/main/kotlin/org/jetbrains/publication.kt | 18 | ||||
| -rw-r--r-- | gradle.properties | 3 |
9 files changed, 85 insertions, 74 deletions
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 40533252..e2a66c91 100644 --- a/.github/workflows/gh-pages.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e9a7c819..34073a28 100644 --- a/CONTRIBUTING.md +++ b/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" +} +``` diff --git a/build.gradle.kts b/build.gradle.kts index 2dbd12f5..0e45f985 100644 --- a/build.gradle.kts +++ b/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")) } } diff --git a/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt b/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt index 6b78edba..03f607e8 100644 --- a/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt +++ b/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") } } diff --git a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt b/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt index 05585d06..517c7731 100644 --- a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt +++ b/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("-", "")) + } diff --git a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt b/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt index dbf2d312..077cd854 100644 --- a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt +++ b/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()); } diff --git a/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt b/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt index 921ec025..af35a847 100644 --- a/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt +++ b/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,22 +12,21 @@ 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() } @@ -34,8 +34,12 @@ open class ValidatePublications : DefaultTask() { } 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}" + ) } diff --git a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt index c3fc2ac7..10353b97 100644 --- a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt +++ b/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) } } diff --git a/gradle.properties b/gradle.properties index 564b080f..1b8eed4f 100644 --- a/gradle.properties +++ b/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 |