From d2ee3ed587e087f03fb098089780018c6c5491a5 Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 20:43:36 +0800 Subject: [PATCH 1/4] Configure the Dokka Gradle plugin, its tasks, and the GitHub Actions workflow, with code copied and adapted from "gradle-common" A source commit: https://github.com/huanshankeji/gradle-common/commit/d0c81059c453e854043475d9e7f077826ad84c8a --- .github/workflows/dokka-gh-pages.yml | 61 +++++++++++++++++++ build.gradle.kts | 18 ++++++ buildSrc/build.gradle.kts | 1 + .../main/kotlin/dokka-convention.gradle.kts | 12 ++++ .../main/kotlin/lib-conventions.gradle.kts | 3 +- gradle.properties | 2 + 6 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/dokka-gh-pages.yml create mode 100644 buildSrc/src/main/kotlin/dokka-convention.gradle.kts create mode 100644 gradle.properties diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/dokka-gh-pages.yml new file mode 100644 index 0000000..1fed077 --- /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: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Set up JDK 11 + uses: actions/setup-java@v4 + with: + java-version: "11" + distribution: "temurin" + + - 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 diff --git a/build.gradle.kts b/build.gradle.kts index 1241019..4b8dba2 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,3 +1,21 @@ tasks.wrapper { distributionType = Wrapper.DistributionType.ALL } + +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() +} + +dependencies { + listOf( + "compose-html-common", + "compose-html-material3" + ).forEach { + dokka(project(":$it")) + } +} diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index a100bd9..2586469 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -17,4 +17,5 @@ dependencies { implementation("com.huanshankeji:kotlin-common-gradle-plugins:$huanshankejiGradlePluginsVersion") implementation("com.huanshankeji.team:gradle-plugins:$huanshankejiGradlePluginsVersion") implementation("com.huanshankeji:common-gradle-dependencies:0.8.0-20241016") // don't use a snapshot version in a main branch + implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0-Beta") } 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..77fc338 --- /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/compose-html-material/tree/v${version}/${project.name}") + remoteLineSuffix.set("#L") + } + } +} diff --git a/buildSrc/src/main/kotlin/lib-conventions.gradle.kts b/buildSrc/src/main/kotlin/lib-conventions.gradle.kts index e96eb9e..8d5bd06 100644 --- a/buildSrc/src/main/kotlin/lib-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/lib-conventions.gradle.kts @@ -1,4 +1,5 @@ plugins { id("lib-conventions-without-publishing") id("com.huanshankeji.kotlin-multiplatform-sonatype-ossrh-publish-conventions") -} \ No newline at end of file + id("dokka-convention") +} diff --git a/gradle.properties b/gradle.properties new file mode 100644 index 0000000..4a50b9e --- /dev/null +++ b/gradle.properties @@ -0,0 +1,2 @@ +# for Dokka +org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled From 314a8e1198bfcbc4c326645ce531951c9fffc40c Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Wed, 6 Nov 2024 10:17:35 +0800 Subject: [PATCH 2/4] Resolve the Dokka "could not resolve" issue with the official solution A source commit: https://github.com/huanshankeji/gradle-common/commit/c1c69c36fc82be8876c516a3dc06570f1271d857 --- build.gradle.kts | 5 ----- settings.gradle.kts | 8 ++++++++ 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index 4b8dba2..8877da2 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -6,11 +6,6 @@ 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() -} - dependencies { listOf( "compose-html-common", diff --git a/settings.gradle.kts b/settings.gradle.kts index 9cedcae..799d5f2 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -5,3 +5,11 @@ include("compose-html-material-legacy") include("compose-html-material3") include("gradle-plugins") project(":gradle-plugins").name = "compose-html-material-gradle-plugins-legacy" + +// for Dokka +@Suppress("UnstableApiUsage") +dependencyResolutionManagement { + repositories { + mavenCentral() + } +} From a1f4168de1bfbab045dbe95daf2d0bd7a59ea46b Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Wed, 6 Nov 2024 10:54:45 +0800 Subject: [PATCH 3/4] Add a site that includes both the API documentation and the demo, including an index.html and a Gradle task to generate the site, and update the workflow file correspondingly --- .github/workflows/dokka-gh-pages.yml | 6 +++--- build.gradle.kts | 14 +++++++++++++ site/index.html | 31 ++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 site/index.html diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/dokka-gh-pages.yml index 1fed077..cbaa277 100644 --- a/.github/workflows/dokka-gh-pages.yml +++ b/.github/workflows/dokka-gh-pages.yml @@ -1,4 +1,4 @@ -name: Deploy the API documentation to GitHub Pages with Dokka +name: Deploy the site to GitHub Pages on: push: @@ -41,12 +41,12 @@ jobs: uses: gradle/actions/setup-gradle@v4 - name: Build the distribution with Gradle Wrapper - run: ./gradlew :dokkaGeneratePublicationHtml + run: ./gradlew :generateSite - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: build/dokka/html/ + path: build/site/ # Deployment job deploy: diff --git a/build.gradle.kts b/build.gradle.kts index 8877da2..62db3b1 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,3 +1,5 @@ +import org.jetbrains.dokka.gradle.tasks.DokkaGeneratePublicationTask + tasks.wrapper { distributionType = Wrapper.DistributionType.ALL } @@ -14,3 +16,15 @@ dependencies { dokka(project(":$it")) } } + +val dokkaGeneratePublicationHtml by tasks.getting(DokkaGeneratePublicationTask::class) +tasks.register("generateSite") { + group = "site" + + val destRootDir = layout.buildDirectory.dir("site") + into(destRootDir) + from(dokkaGeneratePublicationHtml) { + into("api-documentation") + } + from(layout.projectDirectory.dir("site")) +} diff --git a/site/index.html b/site/index.html new file mode 100644 index 0000000..d9e1137 --- /dev/null +++ b/site/index.html @@ -0,0 +1,31 @@ + + + + + + + Compose HTML Material + + + + + + + + + \ No newline at end of file From f1a3f07246bf5712a6b14e04022f16f6cd90a4cf Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Wed, 6 Nov 2024 11:40:58 +0800 Subject: [PATCH 4/4] Rename --- .github/workflows/{dokka-gh-pages.yml => site-gh-pages.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{dokka-gh-pages.yml => site-gh-pages.yml} (100%) diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/site-gh-pages.yml similarity index 100% rename from .github/workflows/dokka-gh-pages.yml rename to .github/workflows/site-gh-pages.yml