From 6e5de03a2c02efb53aa373638c86774930bca2c3 Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 17:20:44 +0800 Subject: [PATCH 1/5] Create dokka-gh-pages.yml with our workflow template --- .github/workflows/dokka-gh-pages.yml | 61 ++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 .github/workflows/dokka-gh-pages.yml diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/dokka-gh-pages.yml new file mode 100644 index 0000000..5cae7a8 --- /dev/null +++ b/.github/workflows/dokka-gh-pages.yml @@ -0,0 +1,61 @@ +name: Deploy the API documentation to GitHub Pages with Dokka + +on: + push: + branches: [ "release" ] + pull_request: + branches: [ "release" ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: macos-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Set up JDK 8 + uses: actions/setup-java@v4 + with: + java-version: "8" + distribution: "zulu" + + - name: Setup Gradle + uses: gradle/actions/setup-gradle@v4 + + - name: Build the distribution with Gradle Wrapper + run: ./gradlew :dokkaGeneratePublicationHtml + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: build/dokka/html/ + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From 502df8e5e2c7e8b8626a87a00ed1caa4d9a58afb Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 17:22:22 +0800 Subject: [PATCH 2/5] Update the OS and JDK distribution in dokka-gh-pages.yml --- .github/workflows/dokka-gh-pages.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/dokka-gh-pages.yml index 5cae7a8..2781a64 100644 --- a/.github/workflows/dokka-gh-pages.yml +++ b/.github/workflows/dokka-gh-pages.yml @@ -24,7 +24,7 @@ concurrency: jobs: # Build job build: - runs-on: macos-latest + runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 @@ -35,7 +35,7 @@ jobs: uses: actions/setup-java@v4 with: java-version: "8" - distribution: "zulu" + distribution: "temurin" - name: Setup Gradle uses: gradle/actions/setup-gradle@v4 From d0c81059c453e854043475d9e7f077826ad84c8a Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 18:44:59 +0800 Subject: [PATCH 3/5] Configure the Dokka Gradle plugin and its tasks with code copied and adapted from "kotlin-common" A source commit: https://github.com/huanshankeji/kotlin-common/commit/157159b4d63117bddba2f3d4e763a43943d2f76d The `dokkaGenerate` tasks fails with the following error: ```text Execution failed for task ':dokkaGeneratePublicationHtml'. > Could not resolve all files for configuration ':dokkaHtmlPluginIntransitiveResolver~internal'. > Cannot resolve external dependency org.jetbrains.dokka:templating-plugin:2.0.0-Beta because no repositories are defined. Required by: root project : > Cannot resolve external dependency org.jetbrains.dokka:dokka-base:2.0.0-Beta because no repositories are defined. Required by: root project : ``` This may be a bug from Dokka. See https://github.com/Kotlin/dokka/issues/2260. --- .github/workflows/dokka-gh-pages.yml | 4 ++-- build.gradle.kts | 18 ++++++++++++++++++ buildSrc/build.gradle.kts | 2 ++ ...igned-version-plugin-conventions.gradle.kts | 1 + .../main/kotlin/dokka-convention.gradle.kts | 12 ++++++++++++ gradle.properties | 2 ++ 6 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 buildSrc/src/main/kotlin/dokka-convention.gradle.kts diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/dokka-gh-pages.yml index 2781a64..53c853c 100644 --- a/.github/workflows/dokka-gh-pages.yml +++ b/.github/workflows/dokka-gh-pages.yml @@ -2,9 +2,9 @@ name: Deploy the API documentation to GitHub Pages with Dokka on: push: - branches: [ "release" ] + branches: [ "plugins-release" ] pull_request: - branches: [ "release" ] + branches: [ "plugins-release" ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: diff --git a/build.gradle.kts b/build.gradle.kts index f2ba312..13392ad 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -2,6 +2,10 @@ tasks.wrapper { distributionType = Wrapper.DistributionType.ALL } +plugins { + id("org.jetbrains.dokka") +} + evaluationDependsOnChildren() task("publishPluginProjectPlugins") { group = "plugin portal" @@ -9,3 +13,17 @@ task("publishPluginProjectPlugins") { val pluginProjects = subprojects.filter { it.name.endsWith("plugins") } pluginProjects.forEach { dependsOn(it.tasks.named("publishPlugins")) } } + + +dependencies { + /* + "common-gradle-dependencies" not added because it's published in a separate branch + "huanshankeji-team-gradle-plugins" not added because it's renamed and more cumbersome to configure, and also because it's only used by us + */ + listOf( + "kotlin-common-gradle-plugins", + "architecture-common-gradle-plugins", + ).forEach { + dokka(project(":$it")) + } +} diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index 6b5e030..db36dd1 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -38,4 +38,6 @@ dependencies { // This is also a bootstrapping dependency. implementation("com.huanshankeji:common-gradle-dependencies:0.7.1-20240314-boostrap") { exclude("org.jetbrains.kotlin") } */ + + implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0-Beta") } diff --git a/buildSrc/src/main/kotlin/aligned-version-plugin-conventions.gradle.kts b/buildSrc/src/main/kotlin/aligned-version-plugin-conventions.gradle.kts index b8b0bbe..93ac02b 100644 --- a/buildSrc/src/main/kotlin/aligned-version-plugin-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/aligned-version-plugin-conventions.gradle.kts @@ -2,6 +2,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask plugins { id("conventions") + id("dokka-convention") } version = alignedPluginVersion diff --git a/buildSrc/src/main/kotlin/dokka-convention.gradle.kts b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts new file mode 100644 index 0000000..6bceb68 --- /dev/null +++ b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts @@ -0,0 +1,12 @@ +plugins { + id("org.jetbrains.dokka") +} + +dokka { + dokkaSourceSets.all { + sourceLink { + remoteUrl("https://github.com/huanshankeji/kotlin-common/tree/v${version}/${project.name}") + remoteLineSuffix.set("#L") + } + } +} diff --git a/gradle.properties b/gradle.properties index 6e2c210..860f258 100644 --- a/gradle.properties +++ b/gradle.properties @@ -2,3 +2,5 @@ #kotlin.mpp.stability.nowarn=true # More memory is needed to build "architecture-common-gradle-plugins" since Kotlin 2.0.0 org.gradle.jvmargs=-Xmx2G +# for Dokka +org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled From 894a09f38eb5cabc017230bb580fd1b19da4780d Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 18:49:44 +0800 Subject: [PATCH 4/5] Fix the source link URL --- buildSrc/src/main/kotlin/dokka-convention.gradle.kts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildSrc/src/main/kotlin/dokka-convention.gradle.kts b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts index 6bceb68..ac6e6ac 100644 --- a/buildSrc/src/main/kotlin/dokka-convention.gradle.kts +++ b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts @@ -5,7 +5,7 @@ plugins { dokka { dokkaSourceSets.all { sourceLink { - remoteUrl("https://github.com/huanshankeji/kotlin-common/tree/v${version}/${project.name}") + remoteUrl("https://github.com/huanshankeji/gradle-common/tree/v${version}/${project.name}") remoteLineSuffix.set("#L") } } From c8f99f38057f2634be176d7b96d5934624400e30 Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 19:09:30 +0800 Subject: [PATCH 5/5] Workaround the issue in commit d0c81059c453e854043475d9e7f077826ad84c8a --- build.gradle.kts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/build.gradle.kts b/build.gradle.kts index 13392ad..8259f79 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -6,6 +6,11 @@ plugins { id("org.jetbrains.dokka") } +// workaround for https://github.com/Kotlin/dokka/issues/3903 from https://github.com/Kotlin/dokka/issues/2260 TODO remove when it's fixed +repositories { + mavenCentral() +} + evaluationDependsOnChildren() task("publishPluginProjectPlugins") { group = "plugin portal"