From 39fb14c48df950e10371b6daaf75bcba2d72b1ba Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 12:19:33 +0800 Subject: [PATCH 1/4] Initially add code to generate KDoc HTML with Dokka --- build.gradle.kts | 25 +++++++++++++++++++ buildSrc/build.gradle.kts | 1 + .../main/kotlin/common-conventions.gradle.kts | 1 + .../main/kotlin/dokka-convention.gradle.kts | 21 ++++++++++++++++ gradle.properties | 2 ++ 5 files changed, 50 insertions(+) create mode 100644 buildSrc/src/main/kotlin/dokka-convention.gradle.kts diff --git a/build.gradle.kts b/build.gradle.kts index 1241019..67bc02e 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,3 +1,28 @@ +import com.huanshankeji.cpnProject + tasks.wrapper { distributionType = Wrapper.DistributionType.ALL } + +plugins { + id("org.jetbrains.dokka") +} + +dependencies { + listOf( + "core", + "net", + "web", + + "arrow", + "coroutines", + "exposed", + "ktor:client", + "reflect", + "serialization", + "vertx", + "vertx:with-context-receivers", + ).forEach { + dokka(cpnProject(project, ":$it")) + } +} diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index bf8774c..6a6f9e2 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -19,4 +19,5 @@ dependencies { implementation(kotlin("gradle-plugin", "2.0.10")) implementation("com.huanshankeji:common-gradle-dependencies:0.8.0-20241016") // don't use a snapshot version in a main branch implementation("com.huanshankeji.team:gradle-plugins:0.6.0") // 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/common-conventions.gradle.kts b/buildSrc/src/main/kotlin/common-conventions.gradle.kts index 4241d0e..4d9114e 100644 --- a/buildSrc/src/main/kotlin/common-conventions.gradle.kts +++ b/buildSrc/src/main/kotlin/common-conventions.gradle.kts @@ -5,6 +5,7 @@ plugins { id("com.huanshankeji.team.with-group") id("maven-central") id("com.huanshankeji.team.default-github-packages-maven-publish") + id("dokka-convention") } version = projectVersion 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..0ae0853 --- /dev/null +++ b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts @@ -0,0 +1,21 @@ +plugins { + id("org.jetbrains.dokka") +} + +dokka { + // TODO + /* + moduleName.set("Huanshankeji Kotlin Common") + dokkaSourceSets.named("main") { + includes.from("README.md") + sourceLink { + localDirectory.set(file("src/main/kotlin")) + remoteUrl("https://github.com/huanshankeji/kotlin-common/tree/v${version}") + remoteLineSuffix.set("#L") + } + pluginsConfiguration.html { + footerMessage.set("(c) Yongshun Ye") + } + } + */ +} diff --git a/gradle.properties b/gradle.properties index 29f9702..5fc7d29 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,3 +1,5 @@ kotlin.mpp.stability.nowarn=true # needed for the GitHub Actions CI org.gradle.jvmargs=-Xmx4G +# for Dokka +org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled From 29055458c1967fe325b023269410541b307b561d Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 15:48:37 +0800 Subject: [PATCH 2/4] Adjust configuration options and correct the source URL There is a problem that when I open the generated root "index.html" from IntelliJ IDEA, it shows the "kotlin-common-serialization" module. This may be a bug of IntelliJ IDEA, or a bug of Dokka, or the result of my misconfiguration. --- .../main/kotlin/dokka-convention.gradle.kts | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/buildSrc/src/main/kotlin/dokka-convention.gradle.kts b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts index 0ae0853..d214a55 100644 --- a/buildSrc/src/main/kotlin/dokka-convention.gradle.kts +++ b/buildSrc/src/main/kotlin/dokka-convention.gradle.kts @@ -3,19 +3,22 @@ plugins { } dokka { - // TODO - /* - moduleName.set("Huanshankeji Kotlin Common") - dokkaSourceSets.named("main") { - includes.from("README.md") + //moduleName.set("Huanshankeji Kotlin Common") + dokkaSourceSets.all { + //includes.from("README.md") sourceLink { - localDirectory.set(file("src/main/kotlin")) - remoteUrl("https://github.com/huanshankeji/kotlin-common/tree/v${version}") + //localDirectory.set(file("src/main/kotlin")) + remoteUrl( + "https://github.com/huanshankeji/kotlin-common/tree/v${version}/${ + with(project) { + name.removePrefix(parent!!.name + '-') + } + }" + ) remoteLineSuffix.set("#L") } - pluginsConfiguration.html { + /*pluginsConfiguration.html { footerMessage.set("(c) Yongshun Ye") - } + }*/ } - */ } From b06299af90a13ab54cd56ce00104723536f80117 Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 16:09:37 +0800 Subject: [PATCH 3/4] Add a GitHub Actions workflow file to deploy the API documentation to GitHub Pages with Dokka, copied and adapted from https://github.com/huanshankeji/compose-multiplatform-material/blob/main/.github/workflows/demo-gh-pages.yml --- .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..bf93269 --- /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: demo/build/dist/sideBySide/productionExecutable/ + + # 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 101bc0ca48181e42663772ffeea297bacc4c2fd8 Mon Sep 17 00:00:00 2001 From: Shreck Ye Date: Tue, 5 Nov 2024 16:48:17 +0800 Subject: [PATCH 4/4] Update the deployment upload path which was neglected --- .github/workflows/dokka-gh-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/dokka-gh-pages.yml b/.github/workflows/dokka-gh-pages.yml index bf93269..5cae7a8 100644 --- a/.github/workflows/dokka-gh-pages.yml +++ b/.github/workflows/dokka-gh-pages.yml @@ -46,7 +46,7 @@ jobs: - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: demo/build/dist/sideBySide/productionExecutable/ + path: build/dokka/html/ # Deployment job deploy: