From 411808923ee593b6a1627ecb6c0f289bb77f485f Mon Sep 17 00:00:00 2001 From: aSemy <897017+aSemy@users.noreply.github.com> Date: Mon, 13 Mar 2023 16:01:08 +0100 Subject: [PATCH] implement Dokkatoo docs (#30) --- .gitattributes | 3 ++ .github/workflows/deploy-site.yml | 51 ++++++++++++++++++ build.gradle.kts | 14 ++--- buildSrc/build.gradle.kts | 8 ++- buildSrc/repositories.settings.gradle.kts | 17 +++--- .../buildsrc/convention/dokkatoo.gradle.kts | 54 +++++++++++++++++++ .../src/main/kotlin/buildsrc/ext/gradle.kt | 36 +++++++++++++ docs/build.gradle.kts | 39 ++++++++++++++ docs/images/logo-icon.svg | 34 ++++++++++++ docs/styles/logo-styles.css | 44 +++++++++++++++ gradle.properties | 2 +- gradle/libs.versions.toml | 16 ++++-- .../kotka-streams-extensions/build.gradle.kts | 8 +++ modules/kotka-streams-extensions/module.md | 24 +++++++++ .../kotka/extensions/QueryableStoreType.kt | 1 + .../kotka/extensions/namedOperations.kt | 23 ++++---- .../kotka/extensions/state/keyValueStore.kt | 36 ++++++------- .../extensions/streams/BranchedKStream.kt | 2 +- .../kotka/extensions/streams/KStream.kt | 23 +++++--- .../adamko/kotka/extensions/streamsBuilder.kt | 2 + .../adamko/kotka/extensions/tables/KTable.kt | 34 ++++++------ .../kotka-streams-framework/build.gradle.kts | 8 +++ modules/kotka-streams-framework/module.md | 53 ++++++++++++++++++ .../build.gradle.kts | 10 ++++ .../module.md | 36 +++++++++++++ .../dev/adamko/kotka/kxs/KotkaJsonModule.kt | 2 +- settings.gradle.kts | 3 ++ 27 files changed, 497 insertions(+), 86 deletions(-) create mode 100644 .github/workflows/deploy-site.yml create mode 100644 buildSrc/src/main/kotlin/buildsrc/convention/dokkatoo.gradle.kts create mode 100644 docs/build.gradle.kts create mode 100644 docs/images/logo-icon.svg create mode 100644 docs/styles/logo-styles.css create mode 100644 modules/kotka-streams-extensions/module.md create mode 100644 modules/kotka-streams-framework/module.md create mode 100644 modules/kotka-streams-kotlinx-serialization/module.md diff --git a/.gitattributes b/.gitattributes index e566c14..29e3b32 100644 --- a/.gitattributes +++ b/.gitattributes @@ -16,3 +16,6 @@ text eol=lf # (binary is a macro for -text -diff) *.jar binary *.war binary + +# https://github.com/github/linguist/blob/v7.24.1/docs/overrides.md +docs/** linguist-documentation diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml new file mode 100644 index 0000000..728ee95 --- /dev/null +++ b/.github/workflows/deploy-site.yml @@ -0,0 +1,51 @@ +name: Deploy Site + +on: + workflow_dispatch: + push: + tags: + - "v[0-9]+.[0-9]+.[0-9]+" + + +concurrency: + group: "${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}" + cancel-in-progress: true + + +jobs: + + build: + runs-on: ubuntu-latest + steps: + - name: Checkout the repo + uses: actions/checkout@v3 + + - name: Setup JDK + uses: actions/setup-java@v3 + with: + distribution: temurin + java-version: 11 + + - uses: gradle/gradle-build-action@v2 + with: + gradle-home-cache-cleanup: true + arguments: | + :docs:dokkatooGenerate + + - uses: actions/upload-pages-artifact@v1 + with: + path: ./docs/build/dokka/html + + deploy: + needs: build + runs-on: ubuntu-latest + permissions: + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/build.gradle.kts b/build.gradle.kts index e1de2c7..a6460d5 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -1,14 +1,12 @@ import buildsrc.ext.excludeGeneratedGradleDsl +import buildsrc.ext.initIdeProjectLogo plugins { buildsrc.convention.`kotlin-jvm` - buildsrc.convention.`maven-publish` me.qoomon.`git-versioning` - `project-report` // `build-dashboard` // incompatible with Gradle CC - idea } @@ -19,7 +17,6 @@ gitVersioning.apply { branch(".+") { version = "\${ref}-SNAPSHOT" } tag("v(?.*)") { version = "\${ref.version}" } } - // optional fallback configuration in case of no matching ref configuration rev { version = "\${commit}" } } @@ -39,13 +36,6 @@ kotkaPublishing { mavenPomDescription.set("Using Kotka means a more pleasant experience while using Kafka Streams") } - -tasks.wrapper { - gradleVersion = "7.6" - distributionType = Wrapper.DistributionType.ALL -} - - idea { module { isDownloadSources = true @@ -56,3 +46,5 @@ idea { ) } } + +initIdeProjectLogo("site/src/jsMain/resources/ks-logo.svg") diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts index ea3a14d..b2f7e37 100644 --- a/buildSrc/build.gradle.kts +++ b/buildSrc/build.gradle.kts @@ -2,7 +2,6 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile plugins { `kotlin-dsl` - kotlin("jvm") version embeddedKotlinVersion } dependencies { @@ -10,7 +9,12 @@ dependencies { implementation(libs.gradlePlugin.kotlinxSerialization) implementation(libs.gradlePlugin.gitVersioning) - // implementation(libs.gradlePlugin.dokka) // incompatible with Gradle CC + + implementation(libs.kotlin.dokkaCore) + implementation(libs.gradlePlugin.dokkatoo) + + // https://github.com/gradle/gradle/issues/15383#issuecomment-779893192 + implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location)) } val gradleJvmTarget = "11" diff --git a/buildSrc/repositories.settings.gradle.kts b/buildSrc/repositories.settings.gradle.kts index 2591a58..6d6c7fb 100644 --- a/buildSrc/repositories.settings.gradle.kts +++ b/buildSrc/repositories.settings.gradle.kts @@ -1,20 +1,17 @@ +pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + } +} + @Suppress("UnstableApiUsage") // Central declaration of repositories is an incubating feature dependencyResolutionManagement { repositories { mavenCentral() gradlePluginPortal() - jitpack() - } - - pluginManagement { - repositories { - gradlePluginPortal() - mavenCentral() - jitpack() - } } - } diff --git a/buildSrc/src/main/kotlin/buildsrc/convention/dokkatoo.gradle.kts b/buildSrc/src/main/kotlin/buildsrc/convention/dokkatoo.gradle.kts new file mode 100644 index 0000000..b582f6a --- /dev/null +++ b/buildSrc/src/main/kotlin/buildsrc/convention/dokkatoo.gradle.kts @@ -0,0 +1,54 @@ +package buildsrc.convention + +import buildsrc.ext.libs + +plugins { + id("buildsrc.convention.base") + id("dev.adamko.dokkatoo-html") +} + +val kafkaJavadocUrl = libs.versions.kafka.map { v -> + val (major, minor) = v.split(".") + "https://kafka.apache.org/${major}${minor}/javadoc/" +} + +dokkatoo { + dokkatooSourceSets.configureEach { + externalDocumentationLinks.create("kafka-streams") { + enabled.set(true) + url(kafkaJavadocUrl) + } + } +} + +tasks.dokkatooGeneratePublicationHtml { + doLast { + outputDirectory.get().asFile.walk() + .filter { it.isFile && it.extension == "html" } + .forEach { file -> + file.writeText( + file.readText() + .replace( + """""", + """""", + ) + .replace( + """ +